Documentation
Shield docsWork with your project

Connect Claude Code and Codex

Shield setup registers native hooks and MCP tools for a project. Hooks check supported tool requests; MCP lets the agent inspect policy and propose changes. For your first installation, follow the setup guide.

Which part does what?

Part What you use it for
Native hooks Check supported requests from the agent’s ordinary tools against active policy.
Shield MCP tools Let the agent inspect policy, read guides, evaluate diagnostic requests, and prepare reviewed changes.
Operator CLI Initialize the project and confirm settings or policy changes yourself.

After setup, restart and trust the agent so it loads both integrations. Use shield history list to inspect recorded requests and completion.

Install or repair an integration

Initialize the project with shield init, then run shield mcp setup --agent claude in an operator terminal to install native command hooks and Shield’s project MCP entry. Confirmation shows the owned files, binary and project. Claude uses .claude/settings.local.json and .mcp.json. To add Codex as well, run shield mcp setup --agent codex; Codex uses .codex/hooks.json and .codex/config.toml. No user/global settings are changed. When active rules ask for Codex prefix rules, Shield also writes .codex/rules/shield.rules. Setup and every activation rewrite it, removing it when no such rule remains or Codex is removed. Codex loads it only for a trusted project. Shield never replaces a file at that path that it did not write; status and the activation receipt say to move such a file aside. Status also reports a stale file and hand edits, and shield mcp setup repairs them. Until then, Codex Asks block whatever the Ask fallback, because the file may let Codex skip its sandbox. Setup and policy reviews list the prefixes a change adds or removes.

Other hook groups, MCP servers, plugins, settings and Codex rules files survive installation and removal. Repeating setup creates one registration per agent. Missing entries can be repaired by selecting the agent again. Edited owned entries conflict; Shield preserves them and requires resolution. shield mcp setup without --agent resumes a confirmed interrupted plan. shield mcp setup --remove removes the agents you select, and with every agent selected removes all owned registrations while preserving policy, approvals and history.

Load the hooks

Restart the agent, trust the project, enable hooks, and approve the MCP connection. In Codex, review hook definitions through /hooks. Shield cannot override host trust or administrator restrictions.

Setup’s Tool permissions page marks tools that can run without prompting. All except policy_apply are marked by default; later setup preserves your choices. Codex uses a prompt server setting with approve for marked tools. Claude adds mcp__shield__<tool> entries to permissions.allow and shield to enabledMcpjsonServers in .claude/settings.local.json.

MCP policy changes need separate approval. Claude opens a confirmation form: Accept applies, while decline or cancel leaves the proposal pending. The form works in default, auto, and bypassPermissions modes, independently of ordinary tool approval. Clients without form elicitation cannot apply. Codex uses its tool approval prompt; never approval policy refuses apply. See MCP review.

Repeating setup repairs missing tool approvals. Unmarking a tool or removing Shield deletes only approvals Shield added; other servers and existing approvals are preserved. Check shield doctor --json for missing or changed files and binaries. Status reports live verification as unverified.

Intercepted requests

PreToolUse checks requests against the registered project’s policy.

Request Check
Claude Read File read.
Claude Write, Edit, MultiEdit, NotebookEdit File write.
Claude Glob, Grep Read of the search path.
Claude Bash and monitor commands Shell policy.
Codex view_image Image-file read; calls naming another environment block.
Codex webrun searches and direct URL opens Web policy, as described below.
Bound project MCP tool calls MCP policy using the stable project connection ID and full arguments.

Configure these bindings through project MCP connections. Unbound servers retain their host behavior. Bound calls whose project settings drift are blocked until setup is reviewed again. Codex’s inner MCP calls from code mode use the same per-call hook path.

Session-management tools pass through to the host’s permissions. For Claude, these include tool loading, task lists and stopping tasks, questions, plan mode, scheduling, subagents, workflows, agent listing, skills, and MCP resource listing. Invoked tools are checked normally, except in remotely running subagents or workflows. Codex passes through plans, questions, permission requests, tool search, timing, subagents, and MCP resource listing.

Unsupported tools ask in Claude and block in Codex. Examples include MCP resource reads; Claude also asks for session messages, worktrees, LSP, PowerShell, and artifacts. Tool messages name supported alternatives where available. A rule cannot add support for an unmodeled tool.

Web requests

Codex webrun supports search_query and open with direct HTTP(S) URLs, including mixed batches of up to 16 operations. Every operation must pass. An optional lineno only positions the view. Opaque result references, clicks, and other actions block the entire call. Submit a direct URL when available. The hook sees the initial URL, not later redirect destinations.

Protected files and policy changes

Claude can read and commit .shield/config.yml, rules.yml, and shield.lock, but cannot edit them or read .shield/review/. Reading agent settings or .mcp.json asks because they may hold credentials. .shield/.gitignore excludes private review state and cache files. Change configurable protection with shield protection set.

Agents cannot run Shield’s operator CLI. They inspect policy through MCP, prepare proposals, and submit policy_apply with the returned apply_arguments. You can also review proposals with shield policy review. A proposal changes no permissions until accepted.

The first relevant Ask supplies candidate pack/rule guidance and a proposal route separately from the user-facing permission message. Ordinary allowed Claude requests and Shield MCP hook checks add no extra model context. For project scripts, inspect definitions, lifecycle hooks, and arguments before proposing a rule.

Shell denials name up to three denied command forms and their matching rule IDs when that evidence is available. Inspect those rules with rule_list before proposing an allowance. A command can be denied for its argument form even when its input file is readable; folder-access suggestions require a matching outside-location failure.

Claude Ask reads and shell requests use its permission prompt or SDK callback; without a permission host, they block. Stored grants belong to the separate SDK consumer and cannot authorize native-hook retries. Arguments containing only an unresolved exit-status expansion ($? or ${?}), such as echo "exit $?", keep ordinary approval instead of requiring a rewrite. Shield does not guess the status or propose exact literal arguments for it. Explicit command denials still block these requests; other unresolved expansions retain their existing rewrite requirements.

File reads

Read-only text filters can use file-read policy when their only command match is a yielding fallback or no rule matches. The supported jq forms include string interpolation, arrays and objects (including shorthand fields such as {id, decision}), slices, selections, regular-expression tests and output formats such as @tsv. Environment access, module loading, extra-input helpers and file-loading options keep ordinary command review. Explicit command Ask/Deny rules retain precedence. Pagers such as less and more require command approval or a command rule; permission to read their input files does not authorize their execution.

Temporary and session files

Claude and Codex native adapters include the system temporary folders in the read/write location unions. On Unix this includes existing /tmp and /var/tmp roots plus the native per-user temporary directory; macOS aliases resolve to their actual directories. Existing and newly created temporary files need no folder proposal or session ownership check. Explicit command/rule denials and protected Shield files still apply. Removing or replacing a temporary root itself is blocked. This access does not edit project access_paths.

Temporary environment overrides do not open the home directory, its ancestors or its descendants, including .ssh, .claude and .codex. Shield checks the resolved directory, so a symlink alias cannot bypass that boundary. Custom scratch under home follows ordinary project access or an explicitly reviewed access_paths grant.

For Claude native hooks, the read union also includes the current session’s tool-results directory when its transcript path matches the registered project, session ID and configured Claude directory. This allows inspection of persisted tool output through Read or supported text filters. Outside temporary folders, other sessions, settings, credentials and writes receive no extra access through this session scope. Directory or operand symlinks cannot redirect this scope outside the verified artifact directory. The scope is observed afresh for each callback and is unavailable to MCP diagnostic input.

Status lists supported working-file categories. Runtime assets and scratch folders outside temporary roots are not automatically discovered.

Shell analysis

Bash source retains flags, quoting and compounds for conservative shell analysis. A literal cd to the already known current directory, including cd ., keeps that working-directory context and needs no extra approval unless an explicit command rule asks or denies it. Other directory changes retain conservative handling; returning to the original path after an unresolved change does not restore known context. Heredocs and here-strings supply inline data without an extra approval requirement. The command, output destinations, substitutions and shell interpreter bodies still follow their own policy checks, so writing a quoted heredoc to an approved project file can proceed when both the command and write are allowed. Standalone [ and ] in tests such as if [ -f AGENTS.md ]; then cat AGENTS.md; fi preserve the working-directory evidence for the read. Shield checks every branch against policy; an existence test does not authorize the read or skip checks on a missing file. Codex permitted requests return brief model context without an explicit Allow response or argument rewrite; Ask fallback retains the original policy decision. Exact shell rules match the complete supplied vendor input and available context. Protected-path checks resolve existing symlink targets, including ancestors of new files. Agent shell tools cannot launch Shield’s operator CLI or its literal mcp serve startup sequence under another executable name. Use the registered Shield MCP tools to propose changes and request approval. Allow permits the command; Deny blocks it. Unmatched requests ask. When the only explanation for an Ask is source Shield cannot inspect, such as $(…), eval or sh -c, the hook blocks the request and tells the agent which part to rewrite as literal, separate commands; the rewritten request then gets its actual decision.

Codex approval handling

Codex PreToolUse cannot request native approval. Setup preserves a saved fallback or defaults a new choice to allow for every profile, including Strict. The final review shows it without a separate picker. Allow includes unmatched commands and explicit Ask rules; Deny, unsupported tools and protection failures still block, and so does an Ask on a command a Shield prefix rule covers, which Codex would run outside its sandbox without asking. Repeating shield mcp setup --agent codex preserves a saved Block or Allow choice. History retains policy Ask and the configured handoff, without recording individual approval. Automatic Ask allowance is suspended while a confirmed setup plan needs repair; run shield mcp setup to finish that plan.

Codex also installs PermissionRequest for approvals Codex independently raises. Shield evaluates the request again against current policy. Deny blocks; Ask returns no decision, leaving Codex’s approval flow in control. Policy Allow can resolve the approval using the available host context. An explicit workdir takes precedence; otherwise Shield uses Codex’s reported session cwd for all supported commands. Missing workdir or tool IDs do not change policy Allow into Ask. Fresh policy Allow approves without a prompt or Codex rules file; Ask and Deny still apply. History records missing execution context as incomplete while retaining the policy decision and its actual handoff. The reported session cwd is the evaluation context, not proof of a hidden per-command execution directory. With the blocking fallback, an Ask stopped at PreToolUse never reaches this event. Neither abstention nor completion establishes that a person approved a request.

node --check FILE and node -c FILE are syntax checks, with an optional -- before the single filename. This applies to bare node, /bin/node and /usr/bin/node; other executable paths follow ordinary command policy. When Node has no specific rule beyond a yielding Ask fallback, Shield decides the check through file-read policy. An ordinary readable project source can therefore pass without an Ask fallback or a Node permission pack. Explicit command Ask/Deny rules, outside-folder rules and protected files still apply. Extra runtime flags, stdin and multiple filenames retain ordinary command evaluation. When supplied environment metadata contains Node preload options in NODE_OPTIONS (--require/-r, --import, --loader or --experimental-loader), shell syntax checks also retain execution review because startup code can run.

Submitted relative paths use known request cwd. After a cwd change the analyzer cannot resolve, relative file redirections and supported destructive file operations block because Shield cannot verify their targets. Ordinary file moves into the project root follow policy; replacing or moving protected configuration blocks. Redirections to /dev/null and between numbered descriptors, such as 2>/dev/null or 2>&1, open no project file and need no policy.

Finite literal for loops check their commands through normal policy lookup. A supported loop and its resolved break or continue do not require approval on their own; an explicit policy restriction still applies. For example, if node src/server.js needs approval inside a loop, Shield names that invocation. Unresolved command arguments or unsupported control flow can separately require a rewrite or approval. Using PATH as the loop variable separately asks because it changes which executables the commands select.

For a simple background command such as node src/server.js &, Shield tracks the runtime PID’s origin through $!, pid=$!, and whole-variable copies such as copy="$pid". A supported kill "$copy" can therefore reach the normal Ask flow instead of requiring a rewrite for an unknown operand. Known IFS must preserve a single numeric field for unquoted targets; quoting avoids splitting. Overwrites, uncertain branch values, unsupported mutations, arithmetic, indirect references and values read from files do not establish this provenance. Only positive PID references with supported literal signal options are modeled; process-group and name-based targets retain ordinary evaluation. The PID remains symbolic: Shield does not know its number or verify that the original process is still alive. This analysis never grants policy Allow for the kill; configured Ask handling still applies, including Codex’s Allow fallback. Runtime ownership enforcement requires a runner that owns the child process.

Suggestions and history

Native agents can receive an initial pack suggestion when a retained catalog advertises the analyzed command. One pack can advertise several executable names; multiple matches are alternatives to inspect, rather than a single chosen pack. Suggestion guidance uses short names such as the node rule pack in conversation; tool arguments retain the full reference. Publisher and registry names distinguish packs that share a short name. The full registry/publisher/name reference leads to pack_info, policy_propose and user review through policy_apply. A relevant pack may still ask or deny the invocation. Suggestions preserve the current decision and activate nothing; see catalog refresh.

With the blocking fallback, Codex explains that native approval is unavailable. The message can offer a rule for the exact command, web search or fetched host, or an outside folder. The agent submits that change through policy_apply for your approval, then retries after activation. CLI users can also use shield history list and shield rule add directly. shield request approve does not authorize a native hook retry. Policy Deny requires a policy change and cannot be overridden by ordinary host approval. Web searches and fetches follow web rules; see policy rules. Git/Docker effect hints do not override Allow merely because indirect effects are possible. Hooks use the submitted command and available context; they do not verify execution. The native run flow remains a separate checked execution path.

Shield MCP inspection and proposals remain available. Neither a proposal nor a diagnostic Allow authorizes a command. PostToolUse and Claude PostToolUseFailure record available observations without output/error payloads. After you complete an Ask call, PostToolUse reports the host completion and why the call asked. Completion alone does not prove individual approval. Claude can inspect suggestion_list after the task for eligible recurring reviews. Native completions are unlinked when the pre-call receipt is unavailable. Shell exit success is unknown unless supplied by a supported mapping.

Failure boundary and coverage

An explicit native denial prevents dispatch. The installed command also exits 2 when the Shield process cannot start. A host that skips, disables, kills or times out the hook may continue execution; installation cannot promise fail-closed protection for those outcomes. Direct same-user processes remain outside isolation.

The current implementation installs Unix command hooks. Windows setup refuses. Other agents have no installed native integration. Native hooks cannot consume the separate runner’s stored approval grants.

Claude evaluates policy before showing the prompt; Shield cannot revalidate a changed policy when that host later accepts the answer. Native completion records do not establish who approved the request. Codex’s exec_command hook omits workdir and other execution options, so its reported cwd may differ from the command’s effective workdir. Shield records the context the host actually supplies.