code-context-control 2.61.2__py3-none-any.whl → 2.62.0__py3-none-any.whl

cli/_hook_utils.py

@@ -175,6 +175,17 @@ def load_enforcement_state(project_path: Path | None = None, session_id: str = "
     # session must not grant unlocks (signal files used to survive /clear).
     if session_id and state.get("session_id") and state["session_id"] != session_id:
         return _empty_state(session_id)
+    # Migrate unlock keys written before canonical_key (raw resolve() form):
+    # lookups are canonical now, so re-key at load — old and new forms merge.
+    migrated: dict = {}
+    for k, cats in state.get("unlocked_files", {}).items():
+        try:
+            key = canonical_key(k)
+        except OSError:
+            continue
+        merged = set(migrated.get(key, [])) | set(cats)
+        migrated[key] = sorted(merged)
+    state["unlocked_files"] = migrated
     return state
 
 
@@ -205,6 +216,16 @@ def record_c3_signal(
     save_enforcement_state(state, project_path)
 
 
+def canonical_key(path) -> str:
+    """Canonical unlock-map key: resolved, forward-slash, casefolded.
+
+    Must stay form-identical to services.access_guard.canonicalize()'s canon
+    string for existing paths (parity-tested) — the unlock map and the
+    access evaluator must never disagree about path identity on Windows.
+    """
+    return str(Path(path).resolve()).replace("\\", "/").casefold()
+
+
 def record_unlocked_files(
     paths,
     categories,
@@ -223,7 +244,7 @@ def record_unlocked_files(
         if not fp:
             continue
         try:
-            normalized = str(Path(fp).resolve())
+            normalized = canonical_key(fp)
         except OSError:
             continue
         cats = set(state["unlocked_files"].get(normalized, []))

cli/c3.py

@@ -92,7 +92,17 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.61.2"
+__version__ = "2.62.0"
+
+
+def _compress_file_cli(compressor, path, mode="smart", **kw):
+    """compress_file for human-CLI paths: AccessDenied → error dict, not a
+    traceback. The refusal text names the rule so the operator can act."""
+    from services import access_guard as _ag
+    try:
+        return compressor.compress_file(path, mode, **kw)
+    except _ag.AccessDenied as exc:
+        return {"error": exc.message}
 
 
 def _command_deps() -> CommandDeps:
@@ -1338,7 +1348,7 @@ def _benchmark_extract_preview(full_path: Path, compressor: CodeCompressor, patt
     extracted = ""
 
     if ext in code_exts and not pattern:
-        result = compressor.compress_file(str(full_path), "smart")
+        result = _compress_file_cli(compressor, str(full_path), "smart")
         extracted = result.get("compressed", "") if "error" not in result else f"Error: {result['error']}"
 
     elif ext == ".jsonl" and not pattern:
@@ -1617,7 +1627,7 @@ def _benchmark_delegate_optional(project_path: Path, sample: list[tuple[Path, st
         "Focus on responsibilities, important functions/classes, and notable dependencies."
     )
 
-    compressed_result = compressor.compress_file(str(fpath), "smart")
+    compressed_result = _compress_file_cli(compressor, str(fpath), "smart")
     compressed_context = compressed_result.get("compressed", "") if isinstance(compressed_result, dict) else ""
     if not compressed_context:
         compressed_context = raw_content
@@ -3478,7 +3488,7 @@ def cmd_benchmark(args):
             raw_content = content
         comp_baseline_latencies.append((time.perf_counter() - t_read) * 1000)
         t0 = time.perf_counter()
-        result = compressor.compress_file(str(fpath), "smart")
+        result = _compress_file_cli(compressor, str(fpath), "smart")
         comp_c3_latencies.append((time.perf_counter() - t0) * 1000)
         raw_tokens = count_tokens(raw_content)
         comp_orig += raw_tokens
@@ -3544,7 +3554,7 @@ def cmd_benchmark(args):
                         tmp.write(raw_extracted)
                         tmp_path = tmp.name
                     try:
-                        comp_res = compressor.compress_file(tmp_path, mode="smart")
+                        comp_res = _compress_file_cli(compressor, tmp_path, mode="smart")
                         extracted_text += comp_res.get("compressed", raw_extracted)
                     finally:
                         if os.path.exists(tmp_path):
@@ -5203,6 +5213,9 @@ def cmd_install_mcp(args):
         ]
 
         # ── PreToolUse hooks (enforcement — blocks native tools without prior c3_*) ──
+        # Bash/run_shell_command joined in v2.62: the Access Guard sub-hook
+        # scans shell commands (best-effort); without these matchers PreToolUse
+        # simply never fires for shell — proven bypass, see docs/access-guard.md.
         _pre_matcher_names = [
             read_matcher,
             grep_matcher,
@@ -5210,6 +5223,8 @@ def cmd_install_mcp(args):
             edit_matcher,
             write_matcher,
             *extra_edit_matchers,
+            shell_matcher,
+            "run_shell_command",
         ]
         desired_pre_hooks = [
             {"matcher": m, "hooks": [{"type": "command", "command": hook_pretool_cmd}]}
@@ -5899,6 +5914,120 @@ def _creds_cmd_import(args, project_path: str) -> None:
               "(use --overwrite to replace)")
 
 
+def cmd_access(args):
+    """Access Guard rule management — human-only mutation surface (spec §1)."""
+    sub = getattr(args, "access_cmd", None)
+    if not sub:
+        print("Usage: c3 access {list,add,remove,check} [args]")
+        return
+
+    project_path = getattr(args, "project_path", ".") or "."
+
+    if sub == "list":
+        _access_cmd_list(args, project_path)
+    elif sub == "add":
+        _access_cmd_add(args, project_path)
+    elif sub == "remove":
+        _access_cmd_remove(args, project_path)
+    elif sub == "check":
+        _access_cmd_check(args, project_path)
+    else:
+        print(f"Unknown access subcommand: {sub}")
+
+
+def _access_scope(args) -> str:
+    return "global" if getattr(args, "use_global", False) else "project"
+
+
+def _access_audit(action: str, glob: str, kind: str, scope: str,
+                  project_path: str) -> None:
+    """Ledger + activity log for CLI rule mutations. Identifiers only; failure-safe."""
+    try:
+        from services.activity_log import ActivityLog
+        ActivityLog(project_path).log("access_action", {
+            "kind": "access", "action": action, "glob": glob,
+            "rule_kind": kind, "scope": scope, "via": "cli",
+        })
+    except Exception:
+        pass
+    try:
+        from services.edit_ledger import EditLedger
+        EditLedger(project_path).log_edit(
+            file=f"access://{glob}", change_type=f"access_{action}",
+            summary=f"{action} {kind} rule '{glob}' ({scope}) via `c3 access`",
+            tags=["access", action],
+            detail={"kind": "access", "action": action, "glob": glob,
+                    "rule_kind": kind, "scope": scope},
+        )
+    except Exception:
+        pass
+
+
+def _access_cmd_list(args, project_path: str) -> None:
+    from services import access_guard
+
+    scopes = access_guard.list_rules(project_path)
+    notes = {"builtin": "built-in, always on",
+             "global": "~/.c3/config.json",
+             "project": ".c3/config.json"}
+    for scope in ("builtin", "global", "project"):
+        sec = scopes.get(scope) or {}
+        rules = [(k, g) for k in ("deny", "read_only") for g in sec.get(k, [])]
+        print(f"[{scope}] ({notes[scope]}) — {len(rules)} rule(s)")
+        for kind, glob in rules:
+            print(f"  {kind:<10} {glob}")
+        if sec.get("corrupt"):
+            print("  [warn] access section invalid — scope fails closed "
+                  "(deny-all); fix config.json 'access' by hand")
+    print()
+    print(access_guard.COVERAGE_MATRIX)
+
+
+def _access_cmd_add(args, project_path: str) -> None:
+    from services import access_guard
+
+    scope = _access_scope(args)
+    try:
+        result = access_guard.set_rule(args.glob, args.kind, scope, project_path)
+    except ValueError as exc:
+        print(f"[error] {exc}")
+        return
+    if result["added"]:
+        _access_audit("add", result["glob"], args.kind, scope, project_path)
+        print(f"[OK] Added {args.kind} rule '{result['glob']}' (scope={scope})")
+    else:
+        print(f"[=] Rule already present: '{result['glob']}' "
+              f"({args.kind}, {scope})")
+
+
+def _access_cmd_remove(args, project_path: str) -> None:
+    from services import access_guard
+
+    scope = _access_scope(args)
+    try:
+        result = access_guard.remove_rule(args.glob, args.kind, scope, project_path)
+    except ValueError as exc:
+        print(f"[error] {exc}")
+        return
+    if result["removed"]:
+        _access_audit("remove", result["glob"], args.kind, scope, project_path)
+        print(f"[OK] Removed {args.kind} rule '{result['glob']}' (scope={scope})")
+    else:
+        print(f"[error] no {args.kind} rule matching '{result['glob']}' "
+              f"in {scope} scope")
+
+
+def _access_cmd_check(args, project_path: str) -> None:
+    from services import access_guard
+
+    op = getattr(args, "op", "read") or "read"
+    denial = access_guard.check(args.target, op, project_path)
+    if denial is None:
+        print(f"[OK] {op} allowed: {args.target}")
+    else:
+        print(access_guard.refusal(denial, args.target, op))
+
+
 def cmd_jira(args):
     """Jira Cloud / Data Center credential + workspace management."""
     sub = getattr(args, "jira_cmd", None)
@@ -7199,6 +7328,7 @@ def main():
         "bitbucket": cmd_bitbucket,
         "jira": cmd_jira,
         "creds": cmd_creds,
+        "access": cmd_access,
         "oracle": cmd_oracle,
         "upgrade": cmd_upgrade,
     }

cli/commands/parser.py

@@ -447,6 +447,42 @@ def build_parser(version: str, parse_cli_ide_arg):
     cr_import.add_argument("--overwrite", action="store_true", help="Replace entries already registered in the target scope")
     cr_import.add_argument("--path", dest="project_path", default=".", help="Project directory (default: current)")
 
+    # ── Access Guard (v2.62.0) ──────────────────────────────────────────
+    # Human-only mutation surface (frozen spec docs/access-guard.md §1):
+    # rule changes happen here or in the UI tab, never via an agent tool.
+    p_access = subparsers.add_parser(
+        "access",
+        help="Access Guard — path deny/read-only rules the agent must respect",
+    )
+    access_subs = p_access.add_subparsers(dest="access_cmd")
+
+    ac_list = access_subs.add_parser(
+        "list", help="Show rules per scope (builtin + global + project) and coverage"
+    )
+    ac_list.add_argument("--path", dest="project_path", default=".", help="Project directory (default: current)")
+
+    ac_add = access_subs.add_parser("add", help="Add a rule to the project (or --global) scope")
+    ac_add.add_argument("glob", help="POSIX glob (** crosses directories), e.g. 'secrets/**' or '*.pem'")
+    ac_add.add_argument("--kind", choices=["deny", "read_only"], required=True,
+                        help="deny = no read/write/enumerate; read_only = no write")
+    ac_add.add_argument("--global", dest="use_global", action="store_true",
+                        help="Store in the global scope (~/.c3) so every C3 project enforces it")
+    ac_add.add_argument("--path", dest="project_path", default=".", help="Project directory (default: current)")
+
+    ac_remove = access_subs.add_parser("remove", help="Remove a rule from the project (or --global) scope")
+    ac_remove.add_argument("glob", help="The stored glob to remove (case-insensitive match)")
+    ac_remove.add_argument("--kind", choices=["deny", "read_only"], required=True,
+                           help="Which rule list the glob lives in")
+    ac_remove.add_argument("--global", dest="use_global", action="store_true",
+                           help="Remove from the global scope (~/.c3)")
+    ac_remove.add_argument("--path", dest="project_path", default=".", help="Project directory (default: current)")
+
+    ac_check = access_subs.add_parser("check", help="Test a path: verdict + matched rule + refusal string")
+    ac_check.add_argument("target", help="Path to test (absolute or project-relative)")
+    ac_check.add_argument("--op", choices=["read", "write"], default="read",
+                          help="Operation to evaluate (default: read)")
+    ac_check.add_argument("--path", dest="project_path", default=".", help="Project directory (default: current)")
+
     # ── Oracle Discovery API (v2.32.0) ──────────────────────────────────
     p_oracle = subparsers.add_parser(
         "oracle",

cli/guide/access.html

@@ -0,0 +1,288 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Access Guard — C3 Guide</title>
+  <link rel="stylesheet" href="shared.css">
+  <style>
+    .pill-row { display: flex; gap: 8px; flex-wrap: wrap; margin: 16px 0 28px; }
+    .pill {
+      padding: 4px 12px; border-radius: 999px; font-size: 11px;
+      font-family: var(--mono); border: 1px solid var(--border);
+      color: var(--text-dim); background: var(--bg-3);
+    }
+    .pill-accent { color: var(--cyan); border-color: var(--cyan); }
+    .pill-green  { color: var(--green); border-color: var(--green); }
+    .pill-amber  { color: var(--amber); border-color: var(--amber); }
+    .pill-red    { color: var(--red); border-color: var(--red); }
+
+    .callout {
+      border-left: 3px solid var(--cyan);
+      background: var(--bg-2);
+      padding: 12px 16px;
+      border-radius: 0 var(--radius) var(--radius) 0;
+      margin: 16px 0;
+    }
+    .callout-warn   { border-color: var(--amber); }
+    .callout-danger { border-color: var(--red);   }
+    .callout-good   { border-color: var(--green); }
+    .callout p:last-child { margin-bottom: 0; }
+    .callout strong { color: var(--text); }
+
+    .rule-table th, .rule-table td { padding: 8px 12px; }
+    .rule-table tr:hover { background: var(--bg-3); }
+    .rule-table .k-deny { color: var(--red); font-family: var(--mono); }
+    .rule-table .k-ro   { color: var(--amber); font-family: var(--mono); }
+    .rule-table .k-tag  { font-family: var(--mono); font-size: 12px; }
+
+    .step-grid {
+      display: grid; gap: 12px;
+      grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+      margin: 16px 0;
+    }
+    .step-card {
+      padding: 16px;
+      background: var(--bg-2);
+      border: 1px solid var(--border);
+      border-radius: var(--radius);
+    }
+    .step-card .step-num {
+      display: inline-block; width: 22px; height: 22px;
+      background: var(--cyan); color: #000;
+      border-radius: 50%;
+      text-align: center; line-height: 22px;
+      font-size: 11px; font-weight: 700;
+      margin-right: 8px;
+    }
+    .step-card h4 { display: inline; font-size: 14px; }
+  </style>
+</head>
+<body>
+
+<div class="layout">
+  <!-- Header -->
+  <header class="header">
+    <a href="index.html" class="header-logo">
+      <span class="logo-badge">C3</span>
+      Claude Code Companion
+    </a>
+    <nav class="header-nav">
+      <a href="index.html">Home</a>
+      <a href="getting-started.html">Get Started</a>
+      <a href="workflow.html">Workflow</a>
+      <a href="tools.html">Tools</a>
+      <a href="credentials.html">Credentials</a>
+      <a href="access.html" class="active">Access</a>
+      <a href="bitbucket.html">Bitbucket</a>
+      <a href="oracle.html">Oracle</a>
+      <a href="https://github.com/sponsors/drknowhow" target="_blank" rel="noopener" style="color:#EA4AAA">&#9829; Sponsor</a>
+    </nav>
+    <span class="header-version">v2.62.0</span>
+  </header>
+
+  <!-- Sidebar -->
+  <aside class="sidebar">
+    <div class="sidebar-section">
+      <div class="sidebar-label">On this page</div>
+      <a href="#overview"        class="sidebar-link"><span class="icon">🛡️</span> Overview</a>
+      <a href="#quick-start"     class="sidebar-link"><span class="icon">🚀</span> Quick start</a>
+      <a href="#rules"           class="sidebar-link"><span class="icon">📐</span> Rules &amp; semantics</a>
+      <a href="#builtins"        class="sidebar-link"><span class="icon">🔒</span> Built-in protections</a>
+      <a href="#refusals"        class="sidebar-link"><span class="icon">✋</span> Refusal messages</a>
+      <a href="#coverage"        class="sidebar-link"><span class="icon">🗺️</span> Coverage — honest limits</a>
+      <a href="#cli"             class="sidebar-link"><span class="icon">💻</span> CLI commands</a>
+      <a href="#ui"              class="sidebar-link"><span class="icon">🖥️</span> UI tab &amp; probe</a>
+      <a href="#troubleshooting" class="sidebar-link"><span class="icon">🛠️</span> Troubleshooting</a>
+    </div>
+    <div class="sidebar-section">
+      <div class="sidebar-label">Related</div>
+      <a href="credentials.html"     class="sidebar-link">Credential Vault</a>
+      <a href="workflow.html"        class="sidebar-link">Standard workflow</a>
+      <a href="getting-started.html" class="sidebar-link">First-time setup</a>
+    </div>
+  </aside>
+
+  <!-- Main -->
+  <main class="main">
+    <h1 id="overview">Access Guard</h1>
+    <p class="lead">
+      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.
+    </p>
+
+    <div class="pill-row">
+      <span class="pill pill-red">deny — no read, no write</span>
+      <span class="pill pill-amber">read_only — no write</span>
+      <span class="pill pill-green">tighten-only</span>
+      <span class="pill pill-accent">v2.62.0+</span>
+    </div>
+
+    <div class="callout callout-warn">
+      <p><strong>What this is — and is not.</strong> Access Guard protects a
+      <em>cooperative</em> agent against mistakes and prompt-injection: an
+      agent that names a protected path gets a firm, reasoned refusal at
+      every C3 surface. It is <strong>not a sandbox</strong> — it governs
+      file actions invoked through C3's tools and hooks, but does not
+      isolate raw OS processes or external editors. See
+      <a href="#coverage">Coverage</a> for exactly where each layer
+      holds.</p>
+    </div>
+
+    <h2 id="quick-start">Quick start</h2>
+    <div class="step-grid">
+      <div class="step-card">
+        <span class="step-num">1</span><h4>Add a rule</h4>
+        <p>UI → project → <strong>Access Guard</strong> tab → Add rule, or:</p>
+        <pre><code>c3 access add "secrets/**" --kind deny</code></pre>
+      </div>
+      <div class="step-card">
+        <span class="step-num">2</span><h4>Test a path</h4>
+        <p>Use the tab's <strong>Test path</strong> probe, or:</p>
+        <pre><code>c3 access check secrets/key.txt</code></pre>
+      </div>
+      <div class="step-card">
+        <span class="step-num">3</span><h4>Let it work</h4>
+        <p>Agent attempts on protected paths return
+        <code>[c3-access:denied]</code> refusals that name the rule and tell
+        the agent not to retry.</p>
+      </div>
+    </div>
+
+    <h2 id="rules">Rules &amp; semantics</h2>
+    <p>Rules live in the <code>access</code> section of
+    <code>.c3/config.json</code> (project scope) and
+    <code>~/.c3/config.json</code> (global scope):</p>
+    <pre><code>{
+  "access": {
+    "deny":      ["secrets/**", "*.pem"],
+    "read_only": ["docs/legal/**", "migrations/**"]
+  }
+}</code></pre>
+    <table class="rule-table">
+      <tr><th>Rule kind</th><th>Read</th><th>Write / create / delete</th><th>Appears in search?</th></tr>
+      <tr><td class="k-deny">deny</td><td>✗</td><td>✗</td><td>✗ (never listed or hinted)</td></tr>
+      <tr><td class="k-ro">read_only</td><td>✓ (unless another rule denies)</td><td>✗</td><td>✓</td></tr>
+    </table>
+    <ul>
+      <li><strong>Tighten-only.</strong> There is no <code>allow</code> 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.</li>
+      <li><strong>Globs are POSIX-style</strong>, case-insensitive.
+        <code>**</code> crosses directories, <code>*</code> does not; a
+        pattern without <code>/</code> matches the file name at any depth
+        (<code>*.pem</code> matches <code>a/b/server.pem</code>).</li>
+      <li><strong>deny also means deny-create.</strong> 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.</li>
+      <li><strong>deny also means deny-enumerate.</strong> Search, maps, and
+        listings never reveal a denied file's existence. When any rules are
+        active, search output carries a <code>[c3-access:limited]</code>
+        footer so the agent doesn't conclude "missing" means "doesn't
+        exist".</li>
+      <li><strong>Rule text is not secret.</strong> Refusals and
+        <code>c3_status</code> show the matched glob — the guard protects
+        file contents and existence, not the rule list. Name globs
+        accordingly.</li>
+      <li><strong>All rule changes are human-only</strong> — 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.</li>
+      <li><strong>Local-only in v1.</strong> <code>.c3/</code> is gitignored:
+        rules do not travel with a cloned repo.</li>
+    </ul>
+
+    <h2 id="builtins">Built-in protections (always on)</h2>
+    <p>These apply in every C3 project, with no configuration, and cannot be
+    overridden. If the access config is corrupt or unparseable, that scope
+    fails <em>closed</em> — everything in it is denied until fixed.</p>
+    <table class="rule-table">
+      <tr><th>Paths</th><th>Protection</th><th>Why</th></tr>
+      <tr><td class="k-tag">**/.env*</td><td class="k-deny">deny</td><td>Secrets never enter agent context</td></tr>
+      <tr><td class="k-tag">.c3/secrets.enc · .c3/cred_state.json</td><td class="k-deny">deny</td><td>Credential vault sidecars</td></tr>
+      <tr><td class="k-tag">.c3/** · ~/.c3/**</td><td class="k-ro">write-deny</td><td>Config self-tampering (incl. access rules + credential registry)</td></tr>
+      <tr><td class="k-tag">.claude/settings*.json</td><td class="k-ro">write-deny</td><td>Hook/permission self-modification</td></tr>
+      <tr><td class="k-tag">.git/**</td><td class="k-ro">write-deny</td><td>git hooks are a code-execution vector (reads stay open)</td></tr>
+      <tr><td class="k-tag">C3 install directory</td><td class="k-ro">write-deny</td><td>Agent self-modification (installed layouts only)</td></tr>
+      <tr><td class="k-tag">*.pem · id_rsa* · *.key</td><td class="k-deny">default rule</td><td>Seeded in global scope — visible and removable, unlike builtins</td></tr>
+    </table>
+
+    <h2 id="refusals">Refusal messages</h2>
+    <p>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.</p>
+    <table class="rule-table">
+      <tr><th>Tag</th><th>Meaning</th></tr>
+      <tr><td class="k-tag">[c3-access:denied]</td><td>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.</td></tr>
+      <tr><td class="k-tag">[c3-access:read_only]</td><td>Write refused; reads remain separately evaluated.</td></tr>
+      <tr><td class="k-tag">[c3-access:limited]</td><td>Search/listing footer: results may omit protected paths — a file that doesn't appear may still exist.</td></tr>
+      <tr><td class="k-tag">[c3-access:error]</td><td>The enforcement hook itself failed — native write tools are denied until it loads (fail-closed). See <a href="#troubleshooting">Troubleshooting</a>.</td></tr>
+    </table>
+
+    <h2 id="coverage">Coverage — honest limits</h2>
+    <div class="callout callout-good">
+      <p><strong>Enforced:</strong> C3 MCP tools (any agent that uses C3 —
+      Claude Code, Codex, Gemini, Oracle-connected models) · Claude Code
+      native tools (PreToolUse hooks, fail-closed) · <code>c3_shell</code>
+      (best-effort command scan, advisory).</p>
+    </div>
+    <div class="callout callout-danger">
+      <p><strong>Not enforced:</strong> 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.</p>
+    </div>
+
+    <h2 id="cli">CLI commands</h2>
+    <pre><code>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</code></pre>
+
+    <h2 id="ui">UI tab &amp; probe</h2>
+    <p>Each project's UI gains an <strong>Access Guard</strong> tab: rules
+    grouped by scope (builtins shown locked), an add-rule form, delete with
+    typed confirmation for deny rules, and a <strong>Test path</strong>
+    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.</p>
+
+    <h2 id="troubleshooting">Troubleshooting</h2>
+    <table class="kv-table rule-table">
+      <tr><td class="k-tag">[c3-access:error] on every write</td>
+          <td>The access hook failed to load — this is fail-closed by design.
+          Check <code>.c3/hook_errors.log</code>, rerun
+          <code>c3 install-mcp</code>. C3 MCP tools keep working
+          meanwhile.</td></tr>
+      <tr><td class="k-tag">Everything in a scope denied</td>
+          <td>That scope's <code>access</code> section is corrupt or has an
+          unknown key. Fix the JSON; <code>c3 access list</code> names the
+          scope.</td></tr>
+      <tr><td class="k-tag">Expected file "missing" in search</td>
+          <td>Check <code>c3 access check &lt;path&gt;</code> — deny rules
+          remove files from search entirely (deny-enumerate).</td></tr>
+      <tr><td class="k-tag">Rule not matching</td>
+          <td>Globs are POSIX-style: use forward slashes; remember
+          <code>*</code> does not cross directories — use <code>**</code>.
+          Probe with <code>c3 access check</code>.</td></tr>
+    </table>
+
+    <div class="callout">
+      <p><strong>Relationship to the Credential Vault.</strong> Credentials
+      protect <em>values</em> (never in agent context, injected at the
+      subprocess boundary); Access Guard protects <em>files and folders</em>.
+      The vault's registry and sidecars are covered by Access Guard builtins,
+      and both systems log every mutation to the same edit ledger.</p>
+    </div>
+  </main>
+</div>
+</body>
+</html>

cli/guide/bitbucket.html

@@ -78,6 +78,7 @@
       <a href="workflow.html">Workflow</a>
       <a href="tools.html">Tools</a>
       <a href="credentials.html">Credentials</a>
+      <a href="access.html">Access</a>
       <a href="bitbucket.html" class="active">Bitbucket</a>
       <a href="oracle.html">Oracle</a>
       <a href="https://github.com/sponsors/drknowhow" target="_blank" rel="noopener" style="color:#EA4AAA">&#9829; Sponsor</a>

cli/guide/credentials.html

@@ -87,6 +87,7 @@
       <a href="workflow.html">Workflow</a>
       <a href="tools.html">Tools</a>
       <a href="credentials.html" class="active">Credentials</a>
+      <a href="access.html">Access</a>
       <a href="bitbucket.html">Bitbucket</a>
       <a href="oracle.html">Oracle</a>
       <a href="https://github.com/sponsors/drknowhow" target="_blank" rel="noopener" style="color:#EA4AAA">&#9829; Sponsor</a>

cli/guide/getting-started.html

@@ -21,6 +21,7 @@
       <a href="workflow.html">Workflow</a>
       <a href="tools.html">Tools</a>
       <a href="credentials.html">Credentials</a>
+      <a href="access.html">Access</a>
       <a href="bitbucket.html">Bitbucket</a>
       <a href="oracle.html">Oracle</a>
       <a href="https://github.com/sponsors/drknowhow" target="_blank" rel="noopener" style="color:#EA4AAA">&#9829; Sponsor</a>

cli/guide/index.html

@@ -223,6 +223,7 @@
       <a href="workflow.html">Workflow</a>
       <a href="tools.html">Tools</a>
       <a href="credentials.html">Credentials</a>
+      <a href="access.html">Access</a>
       <a href="bitbucket.html">Bitbucket</a>
       <a href="oracle.html">Oracle</a>
       <a href="https://github.com/sponsors/drknowhow" target="_blank" rel="noopener" style="color:#EA4AAA">&#9829; Sponsor</a>
@@ -258,6 +259,9 @@
       <a href="credentials.html" class="sidebar-link">
         <span class="icon">🔐</span> Credential Vault
       </a>
+      <a href="access.html" class="sidebar-link">
+        <span class="icon">🛡️</span> Access Guard
+      </a>
       <a href="bitbucket.html" class="sidebar-link">
         <span class="icon">🪣</span> Bitbucket
       </a>
@@ -321,6 +325,11 @@
         <div class="nav-card-title">Credential Vault</div>
         <div class="nav-card-desc">Secrets agents can use but never read — keyring storage, injection at the subprocess boundary, cross-project search (v2.58.0+)</div>
       </a>
+      <a href="access.html" class="nav-card">
+        <span class="nav-card-icon">🛡️</span>
+        <div class="nav-card-title">Access Guard</div>
+        <div class="nav-card-desc">Paths agents must never read or write — deny/read-only globs enforced at every C3 surface, with honest coverage limits (v2.62.0+)</div>
+      </a>
       <a href="bitbucket.html" class="nav-card">
         <span class="nav-card-icon">🪣</span>
         <div class="nav-card-title">Bitbucket Data Center</div>

cli/guide/oracle.html

@@ -76,6 +76,7 @@
       <a href="workflow.html">Workflow</a>
       <a href="tools.html">Tools</a>
       <a href="credentials.html">Credentials</a>
+      <a href="access.html">Access</a>
       <a href="bitbucket.html">Bitbucket</a>
       <a href="oracle.html" class="active">Oracle</a>
       <a href="https://github.com/sponsors/drknowhow" target="_blank" rel="noopener" style="color:#EA4AAA">&#9829; Sponsor</a>

cli/guide/tools.html

@@ -80,6 +80,7 @@
       <a href="workflow.html">Workflow</a>
       <a href="tools.html" class="active">Tools</a>
       <a href="credentials.html">Credentials</a>
+      <a href="access.html">Access</a>
       <a href="bitbucket.html">Bitbucket</a>
       <a href="oracle.html">Oracle</a>
       <a href="https://github.com/sponsors/drknowhow" target="_blank" rel="noopener" style="color:#EA4AAA">&#9829; Sponsor</a>