Documentation
Shield docsWrite rules

Writing policy rules

Custom rules set project-specific permissions. Start with one exact command, then add optional arguments or requirements as needed. Use the rule reference for field definitions and policy decisions for precedence.

Read the first two sections for your first rule, or choose a topic:

You want to… Read
Reject an operation when an option is missing Commands and requirements
Accept optional flags, values, or forwarded script arguments Text and argument matching
Constrain working directories or affected files Path restrictions
Understand a compound shell request Wrappers and shell commands
Permit a documentation host or search Web rules
Publish configurable, reusable rules Pack variables and shared rule bodies

Your first rule

Suppose you have reviewed a tool’s verify operation and want to allow it. We use the fictional executable acme-check; substitute your own reviewed tool.

In an initialized project, run shield rule add and choose Exact command arguments (argv). Enter ID verify-project, executable acme-check, arguments ["verify"], and decision Allow. The arguments array excludes the executable. Review and confirm to activate the rule for the project cwd.

The default Complete request form also binds vendor context and environment. Choose the argument form here so the rule can cover more than one exact request.

For YAML, use this complete document. Its cwd condition also covers project subdirectories:

schema_version: 1
kind: custom
capabilities: [structured-rules-v1, argument-rules-v1, location-v1]
rules:
  - id: verify-project
    decision: allow
    conditions:
      domain: argv
      executable: acme-check
      arguments: {kind: exact, values: [verify]}
      cwd: {within: {root: project}}

Merge the rule and capabilities into the file selected by .shield/config.yml. For a new shared file, save it as .shield/rules.yml and set rules: rules.yml in the existing configuration. Run shield policy review, choose manual, and confirm the review to activate your edit.

domain: argv matches an executable and argument list. Here, the executable must be acme-check, the arguments exactly [verify], and cwd inside the project. capabilities declares the syntax used: structured rules, arguments, and locations.

Submitted command Does this rule match?
acme-check verify inside the project Yes; the rule contributes Allow.
acme-check verify --write No; the argument list differs.
acme-check report No; the operation differs.
acme-check verify outside the project No; the cwd condition fails.

A miss leaves the decision to other rules, or Ask if none matches. Protected-file checks and other operations in the same shell request still apply. Inspect the active rule with shield rule list --json, or preview a request through MCP diagnostics without executing it.

Choose the right matching style

Use exact when only one complete argument list should match. Use options when you have reviewed optional flags or value-taking options. Use prefix only when every remaining argument may be unrestricted. For example, allowing the prefix verify also allows verify --write; it does not infer which flags are read-only.

For example, if you have also reviewed acme-check verify --verbose, replace only the first rule’s arguments value with this fragment:

arguments:
  kind: options
  prefix: [verify]
  flags: [--verbose]
  values: []
  operands: false

Now both acme-check verify and acme-check verify --verbose match. The flag is optional. acme-check verify --write and acme-check verify report.txt still miss because the grammar declares neither that flag nor operands. Keep the executable and cwd conditions, then review and activate the edit as before.

Unless marked complete, examples below are fragments for the rules array. Add their required capabilities to the document.

Match commands and enforce requirements

Suppose the fictional acme-db tool must use --read-only. Matching that flag in conditions would leave invocations without it to other rules. Put it in requirements to decide what happens when it is missing.

Merge this complete example into your configured rule file and activate it with shield policy review, as in your first rule:

schema_version: 1
kind: custom
capabilities:
  - structured-rules-v1
  - argument-rules-v1
  - requirements-v1
rules:
  - id: database-readonly
    decision: allow
    conditions: {domain: argv, executable: acme-db}
    requirements:
      arguments:
        kind: options
        prefix: []
        flags: [--read-only]
        values: [--user]
        operands: false
        require_all: [--read-only]
    on_unmet:
      decision: deny
      message: Add --read-only and submit a revised request.
      alternatives: [acme-db --read-only]

Conditions match every acme-db invocation. Requirements demand --read-only, accept an optional --user value, and reject operands. Failure returns the on_unmet decision, Deny:

Request This rule’s result Why
acme-db --read-only Allow The required flag is present.
acme-db --read-only --user analyst Allow The optional value-taking option is declared.
acme-db --user analyst Deny The required flag is absent.
acme-db --read-only --write Deny The requirement does not accept --write.
another-db --read-only No match The executable condition does not match.

Other matching rules and protected-state checks still affect the final decision. Verify the real tool’s behavior before treating an option as read-only.

Require a particular option value

A valued option can also require a specific value. This rule allows aws logs filter-log-events with the acme-read-only profile and denies the same operation with any other profile or none:

  - id: logs-read-only-profile
    decision: allow
    conditions:
      domain: argv
      executable: aws
      arguments:
        kind: options
        leading: {flags: [], values: [--profile, --region]}
        prefix: [logs, filter-log-events]
        flags: []
        values: [--profile, --region, --log-group-name, --filter-pattern,
                 --start-time, --end-time, --limit, --output, --query]
        operands: false
    requirements:
      arguments:
        kind: options
        leading:
          flags: []
          values: [{name: --profile, match: acme-read-only}, --region]
        prefix: [logs, filter-log-events]
        flags: []
        values: [{name: --profile, match: acme-read-only}, --region,
                 --log-group-name, --filter-pattern, --start-time, --end-time,
                 --limit, --output, --query]
        operands: false
        require_all: [--profile]
    on_unmet:
      decision: deny
      message: Use --profile acme-read-only for log filtering.

The conditions declare the operation’s grammar without a profile value, so every request using those options reaches the rule, whether --profile comes before or after the operation. The requirements repeat the grammar and add the value: the match applies to every --profile occurrence in both phases, and require_all counts both phases together. Another profile, a missing profile or a second, different --profile gets the Deny. A request with an option the grammar does not declare does not match the rule; other rules decide it. A pack can replace the literal profile with {var: profile} so each project chooses its own, as described in pack variables below.

Conditions versus requirements

Conditions determine whether a rule applies. Requirements determine its successful or unmet outcome. on_unmet.decision is Ask or Deny, and may carry a short message and up to three static alternatives. Alternatives are candidates that must be evaluated again. They cannot rewrite requests, approve execution or bypass another rule. Put exclusions in requirements when failure should block with an explanation. For an unmet requirement, feedback offers an access_path_add alternative only when the same rule and operation report an outside-location failure. Unknown target evidence, excluded paths and unsupported options do not establish that adding a folder would help.

Match text and arguments

Use a text selector to match one field, such as an executable name or one argument. Use an argument selector to describe the whole list after the executable. For acme-check verify --verbose, the executable is acme-check and the argument list is ["verify", "--verbose"].

Text selectors accept a literal string or one of exact, prefix, one_of, glob or regex. Regex matches the entire field, including alternatives and inline flags. Glob matches individual fields; * does not cross a path separator, and an argv glob never expands into more arguments. Each argument stays separate. Use recursive stars as **/name, dir/**, dir/**/name, or bare ** for the whole field. Other adjacent-star placements, including a**b, *** and bare ** inside a brace alternative, are refused. Use [*][*] for two literal stars. Brace alternatives may contain character classes, such as {[ab],c}; empty or nested alternatives are refused. Argument kinds are any, exact, prefix, sequence, options and restrictive risk_tokens. Options declare arity, leading global options, value predicates, presence/forbidden checks, repetition and parsing settings explicitly. With prefix-leading-v1, a prefix selector can also declare leading options. It consumes those options and their values, matches the operation immediately after them, and leaves the suffix unconstrained. This lets an administration restriction cover unknown suffix options without matching words in option values or later operands.

For reusable allowances, choose a grammar for the operation rather than copying one observed argv. exact matches only the complete literal argument vector. prefix leaves every later argument unrestricted, so it is unsuitable when only reviewed optional flags should be allowed. sequence fixes initial token selectors in prefix and declares a rest: {kind: none}, {kind: any} or {kind: each, match: SELECTOR, min: N, max: N}. Counts default to 0–256.

An options grammar fixes the initial operation in prefix, declares boolean options in flags, value-taking options in values, and positional arguments in operands. Declared options are optional unless required explicitly; unknown options fail matching. operands: false rejects positional arguments; operands: true accepts them without restriction. A bounded operand object declares match, min and max. The -- separator ends option parsing, so flags forwarded through it must be modeled as operands.

Example: permit a project test script and its watch option

Suppose your project’s package.json defines test, and you have reviewed both the script and its --watch behavior. Inspect any pretest and posttest scripts too, because npm can run them as part of the command. Use this rule fragment to cover the base command and that optional forwarded argument:

id: npm-test
decision: allow
conditions:
  domain: argv
  executable: npm
  cwd: {within: {root: project}}
  arguments:
    kind: options
    prefix: [test]
    flags: []
    values: []
    operands:
      match: {exact: --watch}
      min: 0
      max: 1

This covers npm test and npm test -- --watch, including the empty forwarding form npm test --. Other scripts, flags, extra operands and repeated watch arguments do not match. Review script definitions, lifecycle hooks and argument effects before proposing; an allowance permits future edits to the script too. Read rule suggestions for the MCP workflow.

Restrict paths

Use path predicates when the same command should be treated differently depending on the files it affects. A command’s working directory and its target files are different checks: running inside a project does not prove that every operand is inside it.

Choose the check according to what you need to establish:

Check Question it answers
cwd Where does this command start?
targets Are the affected paths that Shield can model inside an allowed location?
argument_paths Do the explicit path arguments satisfy the declared restrictions?

For example, a command started inside the project can still name /path/to/another-project/file.txt. A cwd check alone does not constrain that operand. Path checks depend on the supported operation model described below; they do not turn an arbitrary executable into sandboxed code.

Locations use exact, within or outside path predicates with project, absolute, read or write roots. The latter two bind the approved root unions from project configuration and require access-paths-v1. outside means outside the entire union; an exclusion applies under every referenced root. within can include a root-relative text match.

For a command limited to the project root, use cwd: {exact: {root: project}}. To include subdirectories, use cwd: {within: {root: project}}. The value of exact is a path-reference object, not a path string. Project rules use the portable project root rather than a machine’s absolute checkout path; changing exact to within broadens the rule.

An Allow must cover all affected resource actions. Fixed native rm/rmdir/cp/mv forms and typed file operations account for source and effective destination paths. Bounded native cat, head, tail, wc and nonrecursive ls forms model read operands; unsupported options and helpers retain incomplete coverage. Bare ls reads cwd; - is stdin for the other four commands. Unknown options, unresolved paths and recursive copies cannot establish positive containment. Observations are fresh per request. Fixed operations use direct path facts; bounded search metadata checks are described below. Linux/Windows native acceptance is not established by macOS tests.

Check paths in command arguments

argument_paths checks paths explicitly supplied to a tool without claiming a complete resource model for everything that tool executes. It requires argument-paths-v1, argument-rules-v1 and location-v1; read/write root unions also require access-paths-v1. For example, in a rule’s requirements:

argument_paths:
  grammar:
    kind: options
    prefix: [build]
    flags: [--locked]
    values: [--manifest-path, --target-dir]
    operands: false
  options:
    --manifest-path:
      path: {within: {root: read}}
    --target-dir:
      path:
        within: {root: write}
        exclude: [{root: project, path: .shield}]
      recursive: true

The grammar must parse the complete invocation. Every occurrence of each selected option is checked with physical symlink/ancestor resolution; unknown syntax or unresolved context fails the requirement. operands: {path: ...} beside options checks positional operands. Absent options introduce no paths; use require_all in the grammar when one must be supplied. These checks do not constrain implicit configuration, build scripts, imports or runtime file access. The rule still needs its own execution decision and on_unmet branch.

Search files with grep and ripgrep

Fixed grep forms model a positional pattern followed by explicit regular files. Fixed rg forms search a pattern in explicit files or directories, the working directory when none is given, or list them with --files. Listed flags plus -g, -t, -T, context, count and depth values are modeled. Walks follow no descendant links; explicit operands still follow links and receive containment/exclusion checks. Content searches can honor ignore files and glob filters. Their footprint conservatively includes existing hidden descendants; excluded credential paths still block it. Native callbacks also check protected state, caches and agent settings, using at most 1,024 metadata entries and 32 directory levels. A large or ambiguous footprint requires a narrower directory. --no-ignore without glob filters supplies a visible-only footprint. A --files listing supports --hidden and globs and skips the native content check; declared policy exclusions still apply. Hidden listings retain the existing-entry footprint even with --no-ignore. Stdin, hidden content searches, follow overrides, pattern files and helpers remain unverified. --no-config is optional. Shield trusts ambient ripgrep configuration and evaluates the submitted arguments; flags injected by RIPGREP_CONFIG_PATH are outside these checks. Use --no-config when config-free execution is desired.

Read and transform file content

Fixed sed, awk, jq, sort, uniq, cut, diff and cmp forms model explicit regular-file inputs, including contained symlink targets. Sed supports scripts of p, d, s, y, w, W, r and R commands separated by ; or newlines, each with an optional numeric or $ address or range; s accepts the g, p, number, i/I, m/M and w flags. Files a script writes (w, W, the w flag) are write targets and files it reads (r, R) are read targets; a file name runs to the end of its line. In-place editing (-i, -iSUFFIX, --in-place[=SUFFIX]) makes each input a write target too, plus its backup when a suffix is given; when either name is a symbolic link, the write target is the link itself, which sed replaces. Because GNU sed reads -i WORD as a script and BSD sed reads WORD as a backup suffix followed by the script, such a form counts the targets of both readings and is modeled only when both are. This includes -i '': GNU sed reads the empty word as an empty script and the following script word as another file to edit, so sed -i '' 's/a/b/' notes.txt is also read as editing a file named s/a/b/. When the whole command is that one sed invocation, with literal words and no redirections or variable assignments, it is checked through an agent hook, and it keeps no backup and writes no w file, sed creates nothing it could then edit, so a named input that does not exist adds no target. A backup or w file could create a later input, and so could anything else the command runs, so in those cases a missing input leaves the edit unmodeled. -iSUFFIX means the same to both. Rules decide these targets like any other read or write, so an Allow limited to project reads does not cover an edit. The e command and flag, regex addresses, blocks and GNU’s * backup suffixes remain unmodeled; awk supports print statements of numeric fields, optionally with -F; jq supports field/index lookups and pipes through keys, length, type, sort, unique, values and tostring. Their submitted syntax does not load program files, run helpers or access the environment, and loads no input other than the named targets. Sort output files, uniq’s second output operand and arbitrary programs remain unmodeled. Options precede the program and file operands. A - operand reads standard input. Packs decide whether to allow these forms or ask.

Create directories and files

Fixed mkdir/touch forms model writes; mkdir -p supports new paths but operands containing .. remain unverified. Touch reference/date options and its special - operand remain unverified. For these four models, options precede operands; a leading -- admits literal option-like operands. These models supply resource facts; pack rules choose permissions and supported option subsets.

Understand wrappers and shell commands

Allowing a command does not automatically allow every wrapper around it. Shield looks through supported wrappers to evaluate the inner command, but the wrapper can still require review because it changes how that command runs.

Launch wrappers and child shells are looked through. env, nice, nohup, timeout, command, builtin, exec and sudo with recognized options are unwrapped, and rules decide the command they launch. An inline script run by sh, bash, dash or zsh, by bare name or from /bin, with -c is read as shell source and each command in it is decided. A Deny inside the script blocks the whole request: with a rule that denies sudo, nohup zsh -lc 'make docs; sudo true' is denied. The wrapper or child shell itself still asks, because it changes how the command runs, so a wrapped request never reaches Allow.

Unknown options leave a child shell’s script unread, and an unread script asks. zsh accepts only -c, -e, -u, -v, -x, -l and -f. Its script is read with POSIX rules only when it contains none of the syntax that zsh handles differently: $, backticks, *, ?, [, ], {, }, (, ), ~, ^, #, !, %, a word starting with =, &>, |&, &|, <<<, or >& and <& followed by anything but a descriptor number or -. These characters count even inside quotes.

Rules also cover shell, file, web, mcp and completely bound exact_request inputs. File rules permit SDK reads, for example:

id: notes
decision: allow
conditions:
  domain: file
  action: read
  sources:
    all: {exact: {root: project, path: notes.txt}}

This rule needs location-v1 and structured-rules-v1. See the capability reference for other features. Pack documents also declare identity and release metadata. Their decisions can be scalar or complete monotonic Loose/Recommended/Strict maps; custom decisions are scalar. A pack rule can set fallback: true so it applies only when no other pack decides the request, such as a broad review rule a tool-specific pack replaces.

Allow searches and documentation fetches

Use web rules to describe the searches or hosts an agent may access. A fetch allowance can name one documentation host without allowing every URL.

Web rules decide Claude’s WebSearch and WebFetch and Codex’s searches and direct HTTP(S) URL opens. An open is a typed fetch with method GET. Each search or open in a supported Codex batch is evaluated; Deny blocks the whole call, and Ask follows the configured host approval behavior. Unsupported forms block before policy evaluation. Initial-URL permission does not cover unobserved redirects. This pair allows any search and fetches from one documentation host, and needs regex-v1 and requirements-v1:

- id: search
  decision: allow
  conditions: {domain: web, action: search, query: {regex: "(?s).*"}}
- id: docs
  decision: allow
  conditions: {domain: web, action: fetch}
  requirements:
    url: {schemes: [https], hosts: [docs.example.com]}
  on_unmet: {decision: ask}

Hosts match exactly; list each subdomain. A search can carry project text in its query, so allowing every search is a choice to make deliberately.

Fetch rules also decide plain curl and wget downloads in shell commands. With the docs rule above and a writable project folder, curl -fsS -o guide.html https://docs.example.com/guide is allowed: Shield checks the fetch against web rules and the output file against file rules. This covers GET and HEAD requests with one literal URL, inspection options such as -fsSL, timeouts, retries and -o for curl, and -q, --spider and -O for wget. wget must also pass --no-hsts, because otherwise it rewrites ~/.wget-hsts; without -O or --spider it is excluded. curl long-option values must be separate arguments, such as --output guide.html; wget also accepts --output-document=guide.html. Uploads, request bodies, headers, credentials, cookies, proxies, configuration files (including an existing ~/.curlrc, ~/.wgetrc, or ~/.netrc for wget without --no-netrc) and other options leave the command to your argv rules, as do explicit argv rules for curl or wget. Fetches carry client (agent for WebFetch and Codex opens, shell for curl and wget) and, for shell clients, redirects (follow or none), so a rule can cover only one of them:

- id: docs-downloads
  decision: allow
  conditions:
    domain: web
    action: fetch
    url: {schemes: [https], hosts: [docs.example.com]}
    request_fields: {/client: {exact: shell}}

For local smoke tests, restrict shell fetches to loopback hosts and require redirects to be disabled. This keeps a localhost URL from granting permission to follow a redirect to another host:

- id: local-smoke-tests
  decision: allow
  conditions:
    domain: web
    action: fetch
    url: {schemes: [http, https], hosts: [localhost, "127.0.0.1", "[::1]"]}
    request_fields:
      /client: {exact: shell}
      /redirects: {exact: none}

Ordinary curl GET/HEAD requests match this rule. curl -L and wget requests that follow redirects require another matching rule or approval. Shield’s generated localhost suggestion uses this same scope.

Directory options

Many tools take an option that only says where to work, such as npm --prefix DIR, git -C DIR or make -C DIR. A pack or your project’s rules can declare such an option under directory_options, with the directory-options-v1 capability. When no rule decides a command as written, Shield then matches it as the same command without the option, run from that folder. With this declaration and rule, npm start, npm --prefix . start and npm --prefix /path/to/project start from any folder are all allowed, and npm --prefix /somewhere/else start is not:

directory_options:
  - {executable: npm, option: --prefix, position: anywhere, paths: follow}
rules:
  - id: npm-start
    decision: allow
    conditions:
      domain: argv
      executable: npm
      arguments: {kind: exact, values: [start]}
      cwd: {within: {root: project}}

paths is required: follow when the tool resolves other relative paths against the chosen folder, unchanged when it does not, as with cargo --manifest-path; then only a folder equal to the current one is normalized. An option whose value names a file, such as a manifest, sets value: file and lists the default names in files (files: [Cargo.toml]); a value naming any other file leaves the command as written. Other fields set the value forms, position and how repeats combine:

Field Values and default
forms separate, equals, attached; long options default to separate/equals, short options to separate/attached. Attached values require a single-letter short option.
position leading (default) or anywhere before --.
value directory (default) or file; file values require files.
repeat refuse (default), last, or chain to resolve each relative value against the previous one.
paths Required: follow or unchanged.

A rule written for the command as typed keeps deciding it. Values with ~, $ or backquotes left after shell analysis, missing values and undeclared forms leave the command as written.

Unknown keys, source nulls, duplicate keys, and unsupported schemas are rejected. See the rule reference for fields and capabilities. Policy comparisons outside the finite literal model report incomplete.

Pack variables, preconditions and templates

A pack can declare typed variables that each project sets for its own selection, such as a package manager or a cloud profile. A rule or precondition uses {var: NAME} wherever a text selector is accepted, and when tests switch entries on for particular values. Shield fills in values when it prepares the policy, so hooks evaluate ordinary literal rules. An entry that refers to a variable without a value is inactive: unset means no check.

preconditions gate the whole pack. When a precondition’s conditions match and none of its requires_any objects holds, the pack answers with its on_unmet Ask or Deny, even if a more specific pack rule would allow the request. When one object holds, the pack’s ordinary rules decide as usual. A precondition never allows anything. In packs that declare templates-v1, reasons, guidance and on_unmet text can include {{NAME}}, which is replaced by the value.

capabilities: [structured-rules-v1, argument-rules-v1, variables-v1, preconditions-v1, templates-v1]
variables:
  package_manager:
    type: choice
    description: Package manager agents use
    values: [npm, pnpm, yarn]
    suggest: [{file: pnpm-lock.yaml, value: pnpm}]
preconditions:
  - id: package-manager
    conditions: {domain: argv, executable: {one_of: [npm, pnpm, yarn]}, arguments: {kind: any}}
    requires_any:
      - executable: {var: package_manager}
    on_unmet:
      decision: deny
      message: This project uses {{package_manager}}.
rules:
  - id: npx-with-pnpm
    when: [{var: package_manager, equals: pnpm}]
    conditions: {domain: argv, executable: npx, arguments: {kind: any}}
    decision: deny

Variable types are choice, string, list, boolean and path. Use choice with values for a fixed selection, string for text, list for several text values, boolean for conditional activation, and path for a location. Each declaration includes a description; required and default control whether the project must supply a value. See pack configuration for setting values without editing the pack.

Variables are also the pack’s setup flow: shield pack add asks one question per variable in the order the pack declares them. An optional setup object words the question. question replaces the description as the question text, unset labels the answer that leaves an optional variable unset, and value and placeholder label the typed row of a string, path or free-text list. ask_when takes when tests on variables declared earlier and asks only when they hold:

variables:
  profile:
    type: string
    description: Read-only profile agents must use
    layer: local
    setup:
      question: Allow log filtering only with a specific profile?
      unset: Any profile (no check)
      value: Only this profile
      placeholder: acme-read-only
  region:
    type: string
    description: Region agents must use with that profile
    setup:
      unset: Any region
      value: Only this region
      ask_when: [{var: profile, set: true}]

A skipped question keeps the variable’s current value. A required variable without a default cannot use unset or ask_when.

Optional checks

A {var} reference turns its whole entry off while the variable is unset. To keep the rule and drop only one check instead, an option grammar accepts two forms:

  • match: {var: NAME, unset: any} on a valued option accepts any value while NAME is unset, and only the bound value once it is set.
  • An item of require_all, require_any or forbid can be {name: OPTION, when: [TESTS]}; the option is listed only while the tests hold.

With these, one rule allows aws logs filter-log-events with any profile and region until the project sets them, then requires each value that is set:

  - id: logs-filter
    decision: allow
    agents:
      codex:
        prefixes:
          - [aws, logs, filter-log-events]
    conditions:
      domain: argv
      executable: aws
      arguments:
        kind: options
        leading: {flags: [], values: [--profile, --region]}
        prefix: [logs, filter-log-events]
        flags: []
        values: [--profile, --region, --log-group-name, --filter-pattern]
        operands: false
    requirements:
      arguments:
        kind: options
        leading:
          flags: []
          values:
            - {name: --profile, match: {var: profile, unset: any}}
            - {name: --region, match: {var: region, unset: any}}
        prefix: [logs, filter-log-events]
        flags: []
        values:
          - {name: --profile, match: {var: profile, unset: any}}
          - {name: --region, match: {var: region, unset: any}}
          - --log-group-name
          - --filter-pattern
        operands: false
        require_all:
          - {name: --profile, when: [{var: profile, set: true}]}
          - {name: --region, when: [{var: region, set: true}]}
    on_unmet:
      decision: deny

The rule has no message, because a template naming an unset variable would turn the rule off. Agents are told what failed instead, for example --profile must be acme-read-only. or Missing required option: --profile.

Shield checks a pack’s rules with every conditional item listed, whatever its when tests. An option that one item requires and another forbids is refused even when their tests can never hold together.

Codex prefix rules

agents.codex.prefixes, which needs the agent-outputs-v1 capability, lists the command prefixes Codex may run outside its sandbox. That matters for commands such as aws that need the network. While the rule is active and allows, Shield writes each prefix to .codex/rules/shield.rules. A position can list alternatives:

    agents:
      codex:
        prefixes:
          - [aws, logs, filter-log-events]
          - [aws, logs, [tail, get-log-events]]

Each prefix must start with the rule’s own executable and argument prefix, and may add tokens after it. A rule matching aws logs can list [aws, logs, tail] but not [aws] or [aws, s3]. The rule’s executable and argument prefix must be literals or a one_of of literals.

Shield’s hooks still decide every command. When policy asks about a command whose every part matches one of these prefixes, such as aws logs tail --follow, the hook blocks it even under the Allow fallback, because Codex would otherwise run it without asking. A command behind a wrapper such as env or inside bash -c keeps Codex’s sandbox and follows the fallback. Turning the rule off, changing its decision or failing its when removes the prefix at the next activation. See project setup for when the file is written. shield rule list --json reports, for each entry that depends on variables or is overridden, the values it used and the resolved rule, or why it is inactive. Project custom rules do not accept variables, when or templates.

Share rule bodies in a pack

Packs can share one rule body across commands. Project custom rules use independent rules.

Declare invocations and command_sets on the pack, then reference them from a rule. They require invocation-groups-v1 and command-sets-v1 respectively. This pack fragment shares an inspection body between two commands and two leading argument forms:

invocations:
  globals: {id_prefix: v, segments: [[[], [--plain]]]}
command_sets:
  inspection: {status: base-status, diff: base-diff}
rules:
  - id: inspection
    invocation: globals
    command_set: inspection
    conditions: {domain: argv, executable: acme, arguments: {kind: any}}
    decision: allow

The acme --plain status match has ID v1-base-status. Requirements inspect the complete original argv. Groups declare finite exact vectors; they do not guess global options or strip unknown arguments. Each command set belongs to one rule body. shield rule list --json includes shared definitions alongside canonical bodies; an exact matched rule_ref returns its complete argument condition. Human pack summaries count stored bodies, invocation groups and command members separately.

Next steps

Use the rule reference for field lookup, pack validation to check candidate documents, and Project MCP to prepare a change with an agent. If a rule behaves unexpectedly, inspect the actual request with the troubleshooting guide.