Access Guard

Mark the paths an AI agent must never read, never write, or may only touch after you say so — and have every C3 surface enforce it. Four rule kinds in your project (or global) config, one evaluator, refusals that tell the agent exactly why and what to do instead.

Quick start

c3 access add "secrets/**" --kind deny

c3 access add "infra/**" --kind confirm

c3 access check secrets/key.txt

Rules & semantics

Rules live in the access section of .c3/config.json (project scope) and ~/.c3/config.json (global scope):

{
  "access": {
    "deny":      ["secrets/**", "*.pem"],
    "read_only": ["docs/legal/**", "migrations/**"],
    "confirm":   ["infra/**", "*.tf"]
  }
}

There is a fourth kind, mask — reads stay open but come back transformed. It's its own subsystem with its own guide: Mask Guard.

• Precedence: deny > mask > read_only > confirm. Confirm is the loosest non-allow outcome: a hold can be approved into a write, a read_only cannot. Everything stricter wins when rules overlap. A user's read_only rule is never softened into a pause by a confirm rule beside it, and mask beats confirm because an edit made against a transformed view can never be trusted against the real file.
• confirm is write-only, by design. There's no read-confirm knob. Pausing on read already exists as deny plus an Override Request. A confirm hold files that request for you automatically; see Confirm — ask me first.
• Tighten-only. There is no allow list. Scopes merge as a union — a rule anywhere applies everywhere. A project config can only add protection, never grant access; an unknown key in the section is a hard config error.
• Globs are POSIX-style, case-insensitive. ** crosses directories, * does not; a pattern without / matches the file name at any depth (*.pem matches a/b/server.pem).
• deny also means deny-create. Path manipulation and OS aliases (short names, trailing dots/spaces, stream syntax) are normalized before matching, so alternate spellings of a protected name cannot slip past the rule.
• deny also means deny-enumerate. Search, maps, and listings never reveal a denied file's existence. When any rules are active, search output carries a [c3-access:limited] footer so the agent doesn't conclude "missing" means "doesn't exist".
• Rule text is not secret. Refusals and c3_status show the matched glob — the guard protects file contents and existence, not the rule list. Name globs accordingly.
• All rule changes are human-only — UI or CLI, and every mutation is logged to the project's edit ledger. Agents have no tool that can add, remove, or loosen rules.
• Local-only in v1. .c3/ is gitignored: rules do not travel with a cloned repo.

Built-in protections

These apply in every C3 project with no configuration. Tier 0 is absolute: nothing turns it off. Tier 1 is on by default, but each guard now takes an independent mode: deny (tighten to a full block), confirm (pause and ask), allow (off), or default (the shipped behaviour). If the access config is corrupt or unparseable, that scope fails closed — everything in it is denied until fixed.

Tier 0 — absolute, no mode, no opt-out

These already carry their own guard (the vault's own encryption) and their own human-only escalation, so an opt-out here would only be a shorter route to the same secrets. c3 access builtin mode refuses to touch them at any scope, and even an approved **/.c3/** write or a confirm-mode .c3/** can never reach them — see Override Requests.

Tier 1 — mode-governable

**/.grok/hooks/** is Grok Build's hook registration (the command lines it runs) — the same role **/.claude/settings*.json plays for Claude Code.

# every project on this machine
c3 access builtin mode "**/.env*" confirm

# THIS project only — replaces the global mode for that glob
c3 access builtin mode "**/.c3/**" allow --project

# back to shipped behaviour
c3 access builtin mode "**/.env*" default

A project-scope mode is attested under its own keyring realm, so a cloned repo that carries access.builtin_mode in its config changes nothing on a machine that never ran the attestation — the mode lives in this machine's keyring, not in the checkout. See Per-project & the Hub.

Tier 1, confirm-by-default — the agent-config surfaces

Until v2.100.0 these files were fully writable — only after-the-fact artifact capture watched them. An agent could add itself an MCP server, rewrite a hook's body, or edit its own instructions, and nothing paused it. Now every write to any of them holds for your one-tap approval; reads stay open, because an agent must always be able to read its own instructions.

**/.claude/settings*.json stays in the harder Tier 1 row above, not here: hook registration stays a full write-deny while hook bodies pause, because registration is what decides code execution. This tier is mode-governable too: deny hardens it to a write-deny and allow restores the pre-2.100 behaviour, through the same c3 access builtin mode. See Confirm — ask me first for what actually happens when a write here pauses.

Two more paths stay a plain, non-configurable write-deny: the C3 install directory (agent self-modification, installed layouts only) and the credential-vault write guard, which is unconditional and keys off a fixed tool set — no mode reaches it.

*.pem, id_rsa* and *.key are not builtins — they're a default rule seeded into global scope on install, visible in c3 access list and removable like any other rule.

Confirm — ask me first

A confirm rule is the middle mode between "always allowed" and "always refused": the agent may change these files, but every change goes past you first. Reads are untouched. A write refuses softly, and C3 itself (not the agent) files an Override Request the moment the write is blocked.

c3 access add "infra/**" --kind confirm

What happens when a write hits a confirm rule

1. The write is refused with tag [c3-access:confirm] instead of your file being touched.
2. C3 auto-files the request. The agent cannot forget to ask and cannot word the ask — the card is built from the trusted denial (tool, operation, path, rule), never from anything the agent composed. This happens at the PreToolUse hook for native tools and inside c3_edit; every other c3_* tool refuses without filing and says so.
3. You decide on your phone, in the Hub, or with c3 override approve <id> — see Override Requests for all three.
4. One tap mints a single-use, session-bound, path-exact grant. The agent retries the exact same call, on the same surface — a grant matches on tool, so a hook-filed native Edit hold is not satisfied by a c3_edit retry.

Precedence

confirm is the loosest non-allow outcome: a hold can be approved into a write, a read_only cannot. So deny > mask > read_only > confirm. A user's read_only rule is never shadowed by the agent-config confirm tier, and a confirm rule you write over **/.c3/** does not outrank the Tier 1 **/.c3/** write-deny. Use c3 access builtin mode "**/.c3/**" confirm for that instead (Built-in protections).

access_confirm defaults on

Override Requests as a whole default off — a project has to opt in before an agent may ask for anything. Confirm rules are the one deliberate exception: writing a confirm rule is itself the opt-in, so the access_confirm layer defaults on and doesn't need override.enabled. Turn it off explicitly with override.layers.access_confirm: false if you want confirm rules to refuse silently, with no auto-filed request, instead.

Shell writes pause too

A confirm rule (and read_only, and the Tier 1 write-denies) governs the write class, and since v2.102.0 that includes c3_shell and native Bash, not just c3_edit. echo >> CLAUDE.md, sed -i on .mcp.json, or a heredoc into a hook body all evaluate the files the command writes as a write and pause the same way an editor write would. See Shell command scan for how the scan finds those targets, and its limits.

Override Requests

Every guard on this page is terminal by default: the only way past a block used to be a human weakening a rule permanently. Override Requests add the missing primitive — a grant that lets one blocked call succeed once, without touching policy. The rule that denied the call is still in force the instant the grant is spent.

What can ever be escalated

Never escalatable, at any setting, by any approval: the credential vault, .c3/secrets.enc, .c3/cred_state.json, .c3/vault_backup.json, the Tier-0 absolute denies, the dispatcher's fail-closed deny, and the catastrophic c3_shell blocks. A denial from one of those never reaches the grants file, and the refusal never mentions that a request surface exists.

The loop: ask, decide, retry

The agent's tool — c3_override

There is no approve action, anywhere in this tool, on purpose. Asking for one by name gets a refusal that says so — approval is human-only, from the phone, the Hub, or c3 override approve.

Who answers

• Desktop CLI — c3 override requests lists pending cards; c3 override approve <id> [--mode once|session|rule] [--confirm <glob>] and c3 override deny <id> [--mute] decide.
• Phone — the mobile app's inbox, Bearer auth on every route, an inbox across every project. The typed-confirm challenge is the rule glob itself, not a nonce: retyping **/.env* costs more than a habit-tap. A requested TTL is clamped and the client is told when it was.
• Desktop Hub — the Access tab, pending cards across every project on the machine, the same typed-glob challenge re-enforced server-side. Under the cards, a read-only policy matrix shows any project's effective rules and override-layer switches. See Per-project & the Hub.

Mute

c3 override deny <id> --mute denies and suppresses identical requests (same project, session, layer, rule, tool, operation and path) for the rest of the session. A new session gets to ask again. The mute store fails open (the opposite of the grant store): a lost mute costs one extra notification, never a capability.

Session and rule-scoped grants

The default grant (mode=once) covers one exact call. Two looser modes exist, both opt-in and both needing their own typed confirmation:

A rule grant relaxes exactly two of the nine match conditions: the exact tool becomes any tool in the same declared class (an unclassed tool, like c3_artifacts or c3_project, never widens), and the exact path becomes the path set the rule glob describes. It still cannot reach a Tier-0 file or the override policy/grant store, even under a **/.c3/** rule — proven live: such a grant covers .c3/notes.txt and never override_grants.json. Rule grants are visible and killable, not just logged: the Hub's Access tab lists active grants with what each one reaches, and can revoke one.

What it costs you

A rule that keeps generating requests is a signal, not just noise. c3 override costs [--days N] [--all] and the Hub's "costing you" strip surface it: how many times a rule held the agent in the trailing window, how you answered, and a suggestion — convert to allow (mostly approved), tighten or deny (mostly denied), or review.

c3 override costs --days 7

Per-project control & the Hub

Two things used to be global-only and are now settable per project: which builtin guards apply, and what override policy a project runs. A third is new outright: editing Access Guard rules across every registered project from one screen.

A project can loosen (or tighten) its own builtins

Global scope used to be the only place that could change a Tier 1 builtin's mode. A project-scope mode now replaces the global one for that glob, loosening included — attested under its own keyring realm (builtin_mode|proj|<path>|<glob>), so cloning the repo never carries the loosened mode to a machine that never attested it.

c3 access builtin mode "**/.env*" confirm --project
c3 access list   # prints [project] / [global] beside each mode

Inherit again, or see one project's whole policy in one read

Setting a mode or an override policy at project scope used to be a one-way trip: nothing meant "go back to whatever global says" except hand-editing the config out. c3 override policy and the enforcement mode now both take a clear, which drops the project's own section and falls back to global (and global falls back to the built-in default). The Hub reads a project's whole effective override policy for every key, whether it's corrupt or even initialized, in one call instead of one request per key.

Access Guard rules across every project, from the Hub

The Hub's Access tab can add or remove a deny / read_only / confirm rule on any registered project, or on global scope, without opening that project. Adding tightens, so it needs no confirmation; removing a deny rule, or any global-scope rule, needs the glob retyped as a confirmation. A folder with no .c3/ is refused rather than silently initialized — a rule C3 does not read protects nothing while claiming to. Every real write lands in the target project's own edit ledger.

"May agents ask?"

The Hub's Access tab also exposes override.enabled itself (the switch that decides whether a request may exist at all), with the seven escalatable layers listed individually and the same two caveats always on screen: policy merges by tightening only, and the credential vault and the catastrophic blocks are never escalatable at any setting. Turning the feature on, or turning a layer on, needs a typed confirmation; turning either off never does.

Shell command scan

c3_shell and native Bash (via the PreToolUse hook) both read a command's tokens and judge each one against Access Guard, per command segment (split on &&, ||, ;, |, and newlines) so a leading cd updates which directory later segments resolve against. Reads are checked against deny-kind rules only; since v2.102.0, the files a command writes (redirects, tee, sed -i, cp/mv, inline Python open(...,'w')) are extracted and evaluated as writes, so a read_only, confirm or write-deny rule holds a shell write exactly like an editor write would.

Spelling rules (no glob — a refusal cites these by name)

<ads> caused the most false positives while the scan matured, all fixed and worth knowing if a command you expect to run gets denied by a rule c3 access list doesn't show:

• URLs and IPv6 (v2.64.0). A residual colon reads as NTFS stream syntax, so https://example.com and fc00::/7 used to hard-deny any command that mentioned one — git commit messages about networking, curl, gh pr create. Scheme-prefixed and IPv6 literal/CIDR tokens are now skipped before evaluation.
• Pytest node ids and git revspecs (v2.76.2). a/b.py::Thing is a node id, never a stream. But a genuine file::$DATA stream still denies, because the discriminator is the $-prefixed type slot. A git <rev>:<path> revspec now has its path half checked instead of the whole token — git show HEAD:.env still denies on .env's own rule.
• The revspec rewrite, for real commands (v2.76.3). The git-revspec fix above only fired when a command started with git — cd /repo && git show origin/main:pyproject.toml was still denied, because that's how the idiom actually arrives. Segment-by-segment fixed it.
• The cwd the command actually runs in (v2.77.0). The existence gate judged every path against the session's project root even after a cd moved somewhere else, so cd <elsewhere> && cat .env was not flagged. Fixed alongside the segment-aware rewrite above — and as a result, a project-scoped rule now correctly stops binding once you cd into a different repo.

Refusal messages

Every denial carries a stable machine tag, the matched rule and scope, and explicit no-retry guidance — so the agent pivots instead of retry-looping or silently recreating "missing" files.

Masked-path tags ([c3-mask:transformed], [c3-mask:limited], [c3-mask:unsupported]) are documented on the Mask Guard page.

Coverage — honest limits

Tool discipline is a separate knob

Access Guard governs paths. A neighboring layer, tool discipline (c3 enforce), governs whether native Edit/Write are blocked in favour of c3_edit at all — a workflow preference, not a security boundary. Loosening it never reaches Access Guard rules, the credential vault, or agent locks; those enforce at every discipline mode.

c3 enforce                    # show the current mode
c3 enforce advisory           # allow native writes, with a nudge
c3 enforce strict             # block until a c3_* call ran first
c3 enforce off                # no nudging
c3 enforce --global advisory  # default for every project on this machine

c3 access stats labels each denial with its layer (path policy vs. tool discipline) and names the exact command that clears it. Full reference: docs/enforcement.md.

CLI commands

# rules
c3 access list                                    # rules by scope, builtins, coverage
c3 access add "secrets/**" --kind deny            # project scope
c3 access add "infra/**" --kind confirm           # pause writes, don't block them
c3 access add "*.pem" --kind deny --global        # global scope
c3 access remove "secrets/**" --kind deny
c3 access check secrets/key.txt                   # probe: verdict + matched rule
c3 access check docs/x.md --op write
c3 access stats                                   # what got denied, how often, how to clear it
c3 access stats --clear

# builtins
c3 access builtin mode "**/.env*" confirm         # deny | confirm | allow | default
c3 access builtin mode "**/.c3/**" allow --project
c3 access builtin disable "**/.git/**"            # legacy spelling of mode allow
c3 access builtin enable "**/.git/**"

# override requests (see Override Requests above)
c3 override policy                                # effective policy + escalatable layers
c3 override requests [--status pending] [--all]
c3 override approve <id> [--mode once|session|rule] [--confirm <glob>]
c3 override deny <id> [--mute]
c3 override list [--session <id>] [--audit N]  # live grants
c3 override grant <path> --session <id> [...]  # mint one directly, no request
c3 override check <path> --session <id>        # would a grant cover this now?
c3 override revoke <grant_id>
c3 override sweep                                 # drop expired/spent grants
c3 override costs [--days 7] [--all]

# Mask Guard — see masking.html
c3 access mask add "data/**" --preset sample_rows --params "count=20,strategy=first"

UI & probe

Project Access tab

Rules grouped by scope (builtins shown with their mode, not just locked), an add-rule form with all three glob-list kinds, delete with typed confirmation for deny rules, a mode selector and scope picker for builtins, and a Test path probe that shows the verdict, matched rule, and the exact refusal the agent would see. The coverage matrix is pinned at the bottom of the tab.

Hub Access tab (desktop, cross-project)

• Pending request cards — approve, deny, or deny+mute, across every project on the machine; typed-glob challenge for deny/builtin approvals.
• Costing you — rules generating the most requests this week, with a suggestion and a jump to that rule.
• Active grants — every live grant, what a rule grant's reach actually covers, and a revoke button.
• Rules panel — add or remove a rule on any registered project, or global scope, without opening it.
• Policy panel — read-only view of any project's effective rules and override-layer switches, plus the "May agents ask?" enable toggle and per-layer switches.

The Hub edits policy and rules; it does not replace the per-project UI — day-to-day rule authoring still happens in the per-project Access tab or c3 access.

Troubleshooting