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

cli/c3.py

@@ -92,7 +92,7 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.62.0"
+__version__ = "2.63.0"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):
@@ -4670,6 +4670,7 @@ back to native tools as the task progresses.
 - **Delegate**: `c3_delegate(task, backend='ollama|codex|gemini|claude|auto')` — offload to other models
 - **Bitbucket** (v2.30.0+, when `c3 bitbucket login` has run): `c3_bitbucket(action='list_prs|get_pr|merge_pr|...')` — self-hosted Bitbucket Data Center / Server. Token in OS keyring; mutating actions auto-log to the edit ledger.
 - **Cross-project** (v2.31.0+): `c3_project(action='list|scan|search|read|edit|...', project='<name|path>')` — discover and operate on OTHER c3-installed projects. Reads run freely; writes (edit/shell/memory) need `allow_write=true`.
+- **Masked paths** (v2.63.0+): content prefixed `[c3-mask:transformed]` is a policy-transformed VIEW, not the file. Values may be synthetic, rows withheld, bodies stripped — don't copy literals out of it or infer completeness from it. Masked paths are read-only and refuse shell/git/validate/impact/filter/delegate (`[c3-mask:unsupported]`). That's policy, not a transient error — report the block instead of routing around it.
 
 ## Self-Check
 If you haven't called a c3_* tool in several turns during active development, re-engage
@@ -5918,7 +5919,8 @@ 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]")
+        print("Usage: c3 access {list,add,remove,check,mask} [args]")
+        print("       c3 access mask {add,rm,status,activate,preview} [args]")
         return
 
     project_path = getattr(args, "project_path", ".") or "."
@@ -5931,6 +5933,8 @@ def cmd_access(args):
         _access_cmd_remove(args, project_path)
     elif sub == "check":
         _access_cmd_check(args, project_path)
+    elif sub == "mask":
+        _access_cmd_mask(args, project_path)
     else:
         print(f"Unknown access subcommand: {sub}")
 
@@ -5973,13 +5977,24 @@ def _access_cmd_list(args, project_path: str) -> None:
     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)")
+        masks = sec.get("mask") or []
+        print(f"[{scope}] ({notes[scope]}) — {len(rules) + len(masks)} rule(s)")
         for kind, glob in rules:
             print(f"  {kind:<10} {glob}")
+        for entry in masks:
+            params = entry.get("params") or {}
+            detail = ", ".join(f"{k}={v}" for k, v in sorted(params.items()))
+            print(f"  {'mask':<10} {entry.get('glob')}  -> "
+                  f"{entry.get('preset')}" + (f"({detail})" if detail else ""))
         if sec.get("corrupt"):
             print("  [warn] access section invalid — scope fails closed "
                   "(deny-all); fix config.json 'access' by hand")
     print()
+    from services import mask_activation
+    summary = mask_activation.summary_line(project_path)
+    if summary:
+        print(summary)
+        print()
     print(access_guard.COVERAGE_MATRIX)
 
 
@@ -6021,11 +6036,174 @@ 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:
+    v = access_guard.verdict(args.target, op, project_path)
+    if v.masked:
+        rule = v.mask_rule
+        print(f"[MASKED] {op} served as a transformed view: {args.target}")
+        print(f"  rule '{rule.glob}' ({rule.scope} scope) -> {rule.preset}")
+        print("  Preview what the agent sees: "
+              f"c3 access mask preview {args.target}")
+    elif v.denial is None:
         print(f"[OK] {op} allowed: {args.target}")
     else:
-        print(access_guard.refusal(denial, args.target, op))
+        print(access_guard.refusal(v.denial, args.target, op))
+
+
+# ── mask subcommands ────────────────────────────────────────────────────────
+
+def _parse_mask_params(raw: str, preset: str) -> dict:
+    """`count=20,strategy=first` / `columns=email,name` -> typed params."""
+    from services import access_guard
+
+    schema = (access_guard.MASK_PRESETS.get(preset) or {}).get("params", {})
+    params: dict = {}
+    for chunk in (raw or "").split(","):
+        chunk = chunk.strip()
+        if not chunk:
+            continue
+        if "=" not in chunk:
+            # bare value continues the previous list param (columns=a,b,c)
+            last = next((k for k in reversed(list(params))
+                         if schema.get(k) is list), None)
+            if last:
+                params[last].append(chunk)
+                continue
+            raise ValueError(f"cannot parse param '{chunk}' — use key=value")
+        key, value = (part.strip() for part in chunk.split("=", 1))
+        expected = schema.get(key)
+        if expected is int:
+            params[key] = int(value)
+        elif expected is list:
+            params[key] = [value]
+        else:
+            params[key] = value
+    return params
+
+
+def _access_cmd_mask_add(args, project_path: str) -> None:
+    from services import access_guard, mask_activation
+
+    scope = _access_scope(args)
+    try:
+        params = _parse_mask_params(getattr(args, "params", "") or "",
+                                    args.preset)
+        result = access_guard.set_mask_rule(args.glob, args.preset, params,
+                                            scope, project_path)
+    except ValueError as exc:
+        print(f"[error] {exc}")
+        return
+    _access_audit("mask-add", result["glob"], args.preset, scope, project_path)
+    verb = "Replaced" if result["replaced"] else "Added"
+    print(f"[OK] {verb} mask rule '{result['glob']}' -> {args.preset} "
+          f"(scope={scope})")
+    print()
+    print(mask_activation.summary_line(project_path))
+    print("Run `c3 access mask activate` to purge pre-mask derived artifacts.")
+
+
+def _access_cmd_mask_remove(args, project_path: str) -> None:
+    from services import access_guard
+
+    scope = _access_scope(args)
+    try:
+        result = access_guard.remove_mask_rule(args.glob, scope, project_path)
+    except ValueError as exc:
+        print(f"[error] {exc}")
+        return
+    if result["removed"]:
+        _access_audit("mask-remove", result["glob"], "mask", scope,
+                      project_path)
+        print(f"[OK] Removed mask rule '{result['glob']}' (scope={scope})")
+    else:
+        print(f"[error] no mask rule matching '{result['glob']}' "
+              f"in {scope} scope")
+
+
+def _access_cmd_mask_status(args, project_path: str) -> None:
+    from services import mask_activation
+
+    st = mask_activation.status(project_path)
+    print(f"rules      : {st['rule_count']}")
+    print(f"status     : {st['status']}")
+    print(f"stale      : {st['stale']}")
+    if st["corrupt_scopes"]:
+        print(f"corrupt    : {', '.join(st['corrupt_scopes'])}")
+    report = st.get("last_report") or {}
+    if report:
+        print(f"last run   : {report.get('views_built', 0)} view(s) built, "
+              f"{len(report.get('failures') or [])} failure(s)")
+        for failure in (report.get("failures") or [])[:10]:
+            print(f"  [fail] {failure['path']}: {failure['detail']}")
+    print()
+    print(mask_activation.summary_line(project_path) or "no mask rules")
+
+
+def _access_cmd_mask_activate(args, project_path: str) -> None:
+    from services import mask_activation
+
+    print("Activating mask rules (purge -> build -> validate)...")
+    report = mask_activation.activate(
+        project_path, rebuild_index=bool(getattr(args, "reindex", False)))
+    print(f"  files matched      : {report['files']}")
+    print(f"  views built        : {report['views_built']}")
+    print(f"  cache entries wiped: {report['cache_entries_removed']}")
+    print(f"  index dropped      : {report['index_dropped']}")
+    print(f"  file memory dropped: {report['file_memory_dropped']}")
+    facts = report.get("facts") or {}
+    print(f"  facts purged       : {facts.get('purged', 0)} "
+          f"(+{facts.get('unknown_purged', 0)} unknown-provenance)")
+    for failure in report.get("failures") or []:
+        print(f"  [fail] {failure['path']}: {failure['detail']}")
+    _access_audit("mask-activate", f"{report['files']} file(s)", "mask",
+                  "project", project_path)
+    print()
+    print(mask_activation.summary_line(project_path))
+
+
+def _access_cmd_mask_preview(args, project_path: str) -> None:
+    """Show exactly what the agent will see. Human surface only."""
+    from pathlib import Path as _Path
+
+    from services import access_guard, mask_mirror
+
+    target = _Path(args.target)
+    if not target.is_absolute():
+        target = _Path(project_path) / args.target
+    v = access_guard.verdict(str(target), "read", project_path)
+    if v.denial:
+        print(access_guard.refusal(v.denial, str(target), "read"))
+        return
+    if not v.masked:
+        print(f"[=] Not masked: {args.target} — the agent sees the real file.")
+        return
+    try:
+        view = mask_mirror.render_for_path(target, project_path)
+    except mask_mirror.MaskUnavailable as exc:
+        print(f"[error] {exc.message}")
+        return
+    print(f"rule    : '{v.mask_rule.glob}' ({v.mask_rule.scope} scope)")
+    print(f"preset  : {v.mask_rule.preset}  {v.mask_rule.params_dict or ''}")
+    print(f"stats   : {view.stats}")
+    print("-" * 70)
+    print(view.with_header(args.target))
+
+
+def _access_cmd_mask(args, project_path: str) -> None:
+    sub = getattr(args, "mask_cmd", None) or "status"
+    handlers = {
+        "add": _access_cmd_mask_add,
+        "rm": _access_cmd_mask_remove,
+        "remove": _access_cmd_mask_remove,
+        "status": _access_cmd_mask_status,
+        "activate": _access_cmd_mask_activate,
+        "preview": _access_cmd_mask_preview,
+    }
+    handler = handlers.get(sub)
+    if handler is None:
+        print(f"[error] unknown mask subcommand '{sub}' — expected one of: "
+              f"{', '.join(sorted(handlers))}")
+        return
+    handler(args, project_path)
 
 
 def cmd_jira(args):

cli/commands/parser.py

@@ -483,6 +483,48 @@ def build_parser(version: str, parse_cli_ide_arg):
                           help="Operation to evaluate (default: read)")
     ac_check.add_argument("--path", dest="project_path", default=".", help="Project directory (default: current)")
 
+    # ── Mask Guard (v2.63.0, docs/mask-guard.md) ────────────────────────
+    # Masking exposes a path but transforms what the agent sees. Rules are
+    # human-only, like the rest of Access Guard.
+    ac_mask = access_subs.add_parser(
+        "mask", help="Mask Guard — expose a path but transform what the agent sees")
+    mask_subs = ac_mask.add_subparsers(dest="mask_cmd")
+
+    am_add = mask_subs.add_parser("add", help="Add or replace a mask rule")
+    am_add.add_argument("glob", help="POSIX glob, e.g. 'data/**' or '*.csv'")
+    am_add.add_argument("--preset", required=True,
+                        choices=["redact_secrets", "redact_columns",
+                                 "sample_rows", "signatures_only"],
+                        help="Deterministic transform applied to matching files")
+    am_add.add_argument("--params", default="",
+                        help="Preset params, e.g. 'count=20,strategy=first' "
+                             "or 'columns=email,name'")
+    am_add.add_argument("--global", dest="use_global", action="store_true",
+                        help="Store in the global scope (~/.c3)")
+    am_add.add_argument("--path", dest="project_path", default=".", help="Project directory (default: current)")
+
+    am_rm = mask_subs.add_parser("rm", help="Remove a mask rule")
+    am_rm.add_argument("glob", help="The stored glob to remove")
+    am_rm.add_argument("--global", dest="use_global", action="store_true",
+                       help="Remove from the global scope (~/.c3)")
+    am_rm.add_argument("--path", dest="project_path", default=".", help="Project directory (default: current)")
+
+    am_status = mask_subs.add_parser(
+        "status", help="Activation state — whether masking is actually in effect")
+    am_status.add_argument("--path", dest="project_path", default=".", help="Project directory (default: current)")
+
+    am_act = mask_subs.add_parser(
+        "activate",
+        help="Purge pre-mask derived artifacts, then build + validate views")
+    am_act.add_argument("--reindex", action="store_true",
+                        help="Also rebuild the code index in the same pass")
+    am_act.add_argument("--path", dest="project_path", default=".", help="Project directory (default: current)")
+
+    am_prev = mask_subs.add_parser(
+        "preview", help="Show exactly what the agent sees for one path")
+    am_prev.add_argument("target", help="Path to preview (absolute or project-relative)")
+    am_prev.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

@@ -74,11 +74,12 @@
       <a href="tools.html">Tools</a>
       <a href="credentials.html">Credentials</a>
       <a href="access.html" class="active">Access</a>
+      <a href="masking.html">Masking</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>
+    <span class="header-version">v2.63.0</span>
   </header>
 
   <!-- Sidebar -->

cli/guide/bitbucket.html

@@ -79,6 +79,7 @@
       <a href="tools.html">Tools</a>
       <a href="credentials.html">Credentials</a>
       <a href="access.html">Access</a>
+      <a href="masking.html">Masking</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

@@ -88,6 +88,7 @@
       <a href="tools.html">Tools</a>
       <a href="credentials.html" class="active">Credentials</a>
       <a href="access.html">Access</a>
+      <a href="masking.html">Masking</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

@@ -22,6 +22,7 @@
       <a href="tools.html">Tools</a>
       <a href="credentials.html">Credentials</a>
       <a href="access.html">Access</a>
+      <a href="masking.html">Masking</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

@@ -224,6 +224,7 @@
       <a href="tools.html">Tools</a>
       <a href="credentials.html">Credentials</a>
       <a href="access.html">Access</a>
+      <a href="masking.html">Masking</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>
@@ -262,6 +263,9 @@
       <a href="access.html" class="sidebar-link">
         <span class="icon">🛡️</span> Access Guard
       </a>
+      <a href="masking.html" class="sidebar-link">
+        <span class="icon">🎭</span> Mask Guard
+      </a>
       <a href="bitbucket.html" class="sidebar-link">
         <span class="icon">🪣</span> Bitbucket
       </a>
@@ -330,6 +334,11 @@
         <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="masking.html" class="nav-card">
+        <span class="nav-card-icon">🎭</span>
+        <div class="nav-card-title">Mask Guard</div>
+        <div class="nav-card-desc">Expose a path but control what the agent sees — redact secrets, pseudonymise columns, sample rows, signatures only. Deterministic, read-only, fail-closed (v2.63.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>