Documentation
Shield docsWork with your project

Project policy, approvals and history

Use this guide to manage an initialized project: inspect policy, connect agents, review changes, and investigate requests. If this is your first setup, follow your first project first. For the meaning of Allow, Ask, and Deny, read policy decisions.

Choose a task

You want to… Start with
See what is active shield status; use shield doctor for a problem.
Connect or repair an agent Native hooks and MCP setup
Add a reusable permission pack Find and install a pack
Change one project-specific permission Custom rules
Review a change prepared by an agent shield policy review, or the host’s Shield approval prompt.
Let location rules include another directory Additional access paths
Understand a past request Request history

Inspection commands report state. Commands that change policy show a review and require confirmation. The examples below run from your project directory; replace illustrative IDs and paths with values from your own project.

Inspect your project

Run Shield in a project directory, or add --project /path/to/acme. Inspection finds the nearest enrolled ancestor; a nearer enrollment owns its own boundary.

shield status
shield doctor
shield policy show --json
shield rule list --json

status is the everyday overview. Use doctor when something looks wrong: it checks policy loading, registry checkpoints, retained pack sources, and the binary your agents run, and gives repair commands when needed. JSON output provides full structured details for scripts and agents.

If the complete status report cannot be read, doctor returns partial metadata with missing: [complete_status] and a status check. Unreadable retained policy source appears as a policy_source check. These reports require a valid authority checkpoint; they do not repair or replace damaged source. Restore lost retained source before using policy changes to recover the project.

Initialize or revisit setup

Run shield init to review and confirm project policy. It offers the same guided agent setup as shield mcp setup. Mark the agents to configure, or continue with none selected. --agent claude or --agent codex, repeatable, selects directly; --no-setup skips agent setup.

New projects acquire the signed main baseline with Recommended preselected. Choose another profile during setup, pass --profile strict, or use --no-baseline to skip it. Download or verification failure leaves a new project unenrolled. Offline setup can use --no-baseline with supplied artifacts.

Existing packs, rules, profiles, and removals are preserved. Use shield pack remove baseline for later removal. See terminal controls.

Native hooks and MCP setup

Add the agent you want to use, then restart and trust it:

shield mcp setup --agent claude
shield mcp setup --agent codex

Each command installs hooks and MCP while keeping the other agent registered. shield mcp setup without --agent asks which agents to install or repair, or resumes an interrupted confirmed plan. shield mcp setup --remove asks which agents to remove, or takes --agent, and preserves policy, approvals, and history. Add --dry-run to see the review without writing anything. Edited owned entries report a conflict rather than being overwritten.

New Codex setups let valid Ask requests proceed by default, including unmatched requests and Strict-profile Asks. Existing Block or Allow choices are preserved; there is no Block picker or flag. Deny, protected files, and unsupported tools still block. Codex’s own sandbox and approvals also apply.

Status and doctor report the effective Ask fallback. Missing authorization or an interrupted setup can report Block; finish the plan with shield mcp setup. See Ask handling and the integration guide for loading and coverage.

Protected files

shield protection set

By default, native hooks ask before agents read .mcp.json and agent hook settings (.claude/settings.local.json, .claude/settings.json, .codex/hooks.json, .codex/config.toml), which may hold credentials, and block agents from changing them or the .shield policy files.

The same settings protection covers the adapter’s configured agent home, including a relocated home. Verified session-output reads retain their separate scope; they do not permit configuration writes.

protection set asks about each group and confirms the result:

Group Default Other choice
Reading agent settings Ask, or block where the agent cannot prompt Allow without asking
Changing agent settings Block Allow; the agent can then remove Shield’s hooks or the host confirmation that MCP policy changes rely on
Changing .shield policy files Block Allow; edits still apply only after shield policy review

.shield/review/, compiled caches, the .shield folder itself and .shield/.gitignore stay protected whatever you choose, and agents still cannot run shield. The choice is kept with the project’s review state; agents cannot change it. status lists any group you have opened. An invalid saved choice blocks every native request until you run protection set again.

Custom rules and proposed changes

Custom rules express project-specific permissions. For a worked example, see your first rule.

Add, edit, or remove a custom rule

shield rule add

Choose the matching form and decision, then review its scope. After confirming, find the rule’s ID with shield rule list --json. To edit or remove a rule named inspect-status, use the appropriate command:

shield rule edit inspect-status
shield rule remove inspect-status

The default Complete request form binds normalized input, vendor fields, cwd, environment, and executable. Exact command arguments binds an executable and argument array to the project cwd, with broader vendor/environment scope. Both ask for a decision, reason, and optional UTC expiration. Structured rule accepts a complete rule in the rule format.

Editing shows the existing rule; empty answers preserve its conditions. Confirmation activates the validated candidate; cancellation leaves policy unchanged.

Review an agent’s proposal

Agents can propose packs, rules, domain permissions, or folder access. Check whether a proposal covers one invocation or a broader set of requests. To review pending proposals yourself, run:

shield policy review

Proposal review is the default when proposals are pending. They appear oldest first, with the change, agent’s reason, originating command, and permission comparison. Tab opens the complete change, including pack rules. Choose Accept, Reject, or Leave pending; Accept asks for final confirmation.

Agents can also submit a proposal’s exact apply_arguments to policy_apply for host approval. policy_receipt reads the committed receipt. See MCP review.

Changes to policy, setup, registry settings, or cache location can invalidate a proposal. Ask the agent to prepare a fresh one, even if the policy revision has not changed. Independently confirmed protected-file settings remain current. For successive proposals, wait for each result before preparing the next.

Activate a manual file edit

Project policy files represent the committed snapshot. After editing configuration or rules, run shield policy review, choose manual, and confirm the reviewed changes. Inspect shield rule list --json for the active result. Changes during confirmation abort publication. Use shield pack add to acquire releases rather than editing cached pack artifacts.

Shield preserves comments, blank lines, and layout outside changed entries. Removing a rule or pack also removes its preceding comments. If a change cannot be made in place, such as reordering rules, Shield rewrites below the opening comments. The review identifies files that will be rewritten or lose comments.

Additional access paths

If your agent needs a reference folder outside the project, you can add that folder to the roots used by location rules. Adding a root does not itself allow every operation there; the active rules still decide what the agent may do.

Project configuration can bind reusable location rules to additional directories:

access_paths:
  read: [/path/to/reference]
  write: [/path/to/scratch]

Add this mapping to .shield/config.yml, preserving its schema_version, packs and any rules selection, then review the manual action in shield policy review and confirm. An agent can also propose one directory at a time with the MCP access_path_add change, which you confirm the same way. Editing a file alone does not activate access. These settings are retained when installing, updating or removing packs and when changing custom rules.

Rules with {root: read} use the project plus additional read and write roots; {root: write} uses the project plus additional write roots. Write access includes read access. At most 64 additional native absolute directories are accepted; duplicates within each list, traversal components, NULs, null lists and unknown fields refuse. Roots must be observable existing directories when evaluated. An unavailable configured root makes its location predicate unknown.

Native Claude/Codex integrations also include system temporary roots automatically in these unions; no access_paths entry is needed for ordinary temporary files. Claude additionally supplies its verified current-session tool-result read scope. These adapter observations are not stored in policy or accepted from diagnostic tool input. Explicit policy restrictions and protected-file checks still apply.

Access paths bind policy predicates; the selected rules decide which operations are permitted, including removal. They do not install a host filesystem sandbox. Native hook cwd remains inside the enrolled project; absolute operands can refer to additional roots. Protected Shield/operator configuration remains guarded.

Action approvals

Use this workflow only for stored requests from the restricted SDK text-read integration or bounded native runner. To handle an ordinary Claude or Codex permission prompt, use the host’s approval flow. To change future permissions, review a policy change instead. See approval scopes.

shield request list
shield request show REQUEST
shield request approve REQUEST
shield request deny REQUEST

These commands cover restricted text-read and checked native requests together. Approval confirms one stored Ask request for an exact retry, with a five-minute grant. Request resources, origin, project and active policy must still match. Policy denials cannot be approved. Deny cancels a pending request or revokes an unused grant. A consumed grant cannot authorize another execution.

Approval is available only through a controlling terminal. Redirected stdin, JSON mode and intercepted agent tool calls do not supply operator confirmation.

Request history

List requests, then copy an entry ID into shield history show ENTRY:

shield history list
shield history list --denied
shield history list --approved --agent claude
shield history show ENTRY

Entries combine request decisions, operator decisions, and reported completion. Configuration changes are not request entries. Shell entries show the submitted source: the list shows its first line, and show prints the full command and deciding rule. File entries show the action and path, such as write /srv/acme/app.js.

A decision alone does not establish execution. Completion without a reported exit code stays without one; a blocked command is shown as not run. Rewrite refusals appear as ask → blocked (rewrite required), with the explanation and suggested form in the detail view.

Recording and retention

Initialization retains up to 5,000 requests. The history action in shield policy review changes the limit to 1–10,000, disables recording, or clears optional history. Clearing starts a new generation; increasing retention cannot restore deleted records. Policy and authorization records are separate, so clearing history neither removes active policy nor restores consumed grants.

History uses checksummed segments of at most 1 MiB, capped at 64 MiB per current generation. Recovery files, retention rewrites, and readers holding old files can use more storage. Segments reach stable storage on creation and when full; a crash can lose buffered records from the current segment. Observations can be visible before their receipt is recorded.

On rotation, segments containing only requests beyond retention are removed. At the storage cap, the oldest segments are removed even if their requests are within retention. The list then reports evicted_history and may contain fewer entries than the configured limit.

Completions link only to a retained allowed request or Claude Ask handed to host approval with matching operation, agent, session, tool-call ID, surface, and cwd. Without a Shield reference, the complete host identity and operation must identify exactly one request. Missing identity or reused IDs leave the completion unlinked; matching command text alone is insufficient.

Linking completion to Ask preserves that decision and its prompt disposition. It reports host execution, not individual operator approval. Shell exit status stays unknown without structured exit evidence.

Displayed entries are limited to 8 KiB; truncated and missing identify omitted details. Identical deliveries appear once. Changed content under one delivery ID is marked delivery_conflict; torn writes are preserved as degraded history. status reports unavailable optional history separately. Expired and terminal authorization request state is reclaimed independently.