Access Guard

Mark the paths an AI agent must never read, or never write — and have every C3 surface enforce it. Two glob lists in your project (or global) config, one evaluator, refusals that tell the agent exactly why and what to do instead.

deny — no read, no write read_only — no write tighten-only v2.62.0+

What this is — and is not. Access Guard protects a cooperative agent against mistakes and prompt-injection: an agent that names a protected path gets a firm, reasoned refusal at every C3 surface. It is not a sandbox — it governs file actions invoked through C3's tools and hooks, but does not isolate raw OS processes or external editors. See Coverage for exactly where each layer holds.

Quick start

Add a rule

UI → project → Access Guard tab → Add rule, or:

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

Test a path

Use the tab's Test path probe, or:

c3 access check secrets/key.txt

Let it work

Agent attempts on protected paths return [c3-access:denied] refusals that name the rule and tell the agent not to retry.

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/**"]
  }
}

Rule kind	Read	Write / create / delete	Appears in search?
deny	✗	✗	✗ (never listed or hinted)
read_only	✓ (unless another rule denies)	✗	✓

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 (always on)

These apply in every C3 project, with no configuration, and cannot be overridden. If the access config is corrupt or unparseable, that scope fails closed — everything in it is denied until fixed.

Paths	Protection	Why
*/.env	deny	Secrets never enter agent context
.c3/secrets.enc · .c3/cred_state.json	deny	Credential vault sidecars
.c3/ · ~/.c3/	write-deny	Config self-tampering (incl. access rules + credential registry)
.claude/settings*.json	write-deny	Hook/permission self-modification
.git/**	write-deny	git hooks are a code-execution vector (reads stay open)
C3 install directory	write-deny	Agent self-modification (installed layouts only)
.pem · id_rsa · *.key	default rule	Seeded in global scope — visible and removable, unlike builtins

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.

Tag	Meaning
[c3-access:denied]	Operation refused by a deny rule (or a write refused where read_only applies via hooks). Policy, not an error — the agent is told not to retry or route around it.
[c3-access:read_only]	Write refused; reads remain separately evaluated.
[c3-access:limited]	Search/listing footer: results may omit protected paths — a file that doesn't appear may still exist.
[c3-access:error]	The enforcement hook itself failed — native write tools are denied until it loads (fail-closed). See Troubleshooting.

Coverage — honest limits

Enforced: C3 MCP tools (any agent that uses C3 — Claude Code, Codex, Gemini, Oracle-connected models) · Claude Code native tools (PreToolUse hooks, fail-closed) · c3_shell (best-effort command scan, advisory).

Not enforced: a non-Claude agent's raw shell or direct file APIs — including native file tools in non-Claude CLI environments unless they route through C3 tools — external editors, and OS-level access. Renames/moves via shell commands are a known v1 gap. Access Guard is a guardrail for cooperative agents — pair it with OS permissions when you need a real boundary.

CLI commands

c3 access list                        # rules by scope, builtins included
c3 access add "secrets/**" --kind deny            # project scope
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

UI tab & probe

Each project's UI gains an Access Guard tab: rules grouped by scope (builtins shown locked), an add-rule form, delete with typed confirmation for deny rules, and a Test path probe that shows the verdict, matched rule, and the exact refusal the agent would see. The coverage matrix above is pinned at the bottom of the tab.

Troubleshooting

[c3-access:error] on every write	The access hook failed to load — this is fail-closed by design. Check `.c3/hook_errors.log`, rerun `c3 install-mcp`. C3 MCP tools keep working meanwhile.
Everything in a scope denied	That scope's `access` section is corrupt or has an unknown key. Fix the JSON; `c3 access list` names the scope.
Expected file "missing" in search	Check `c3 access check <path>` — deny rules remove files from search entirely (deny-enumerate).
Rule not matching	Globs are POSIX-style: use forward slashes; remember `` does not cross directories — use `*`. Probe with `c3 access check`.

Relationship to the Credential Vault. Credentials protect values (never in agent context, injected at the subprocess boundary); Access Guard protects files and folders. The vault's registry and sidecars are covered by Access Guard builtins, and both systems log every mutation to the same edit ledger.