#!/usr/bin/env python3
"""Summarize the agent-instruction surface for a project.
Inventories AGENTS.md / CLAUDE.md / Codex / Copilot / Gemini instruction files,
parses Codex config.toml for project trust + plugin/feature state (with sensitive
values redacted), and flags drift between Claude and Codex surfaces.
Run as: python3 check_agent_context.py [ROOT] [summary|deep]
Owns effective instruction, permission, hook, path-context, and active-skill routing evidence. It must not treat plugin caches as active installs or follow escaped symlinks.
"""
from __future__ import annotations
import argparse
import fnmatch
import hashlib
import json
import os
import re
import shlex
import shutil
import sys
from collections import Counter, defaultdict
from pathlib import Path
from typing import Optional
SENSITIVE_RE = re.compile(r"(api[_-]?key|token|secret|password|credential)", re.IGNORECASE)
PROJECT_RE = re.compile(r'^\[projects\."(.+)"\]\s*$')
TABLE_RE = re.compile(r'^\[([A-Za-z0-9_.@"\-/]+)\]\s*$')
OPERATIONAL_RULE_RE = re.compile(
r"(Git Safety|Public Issue Replies|Investigation Honesty|Verification|Response Style|Commit|Security)",
re.IGNORECASE,
)
CJK_CONTEXT_RE = re.compile(r"[\u3400-\u9fff\u3040-\u30ff\uac00-\ud7af]")
ASSIGNMENT_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*=.*")
# Assignments that choose the interpreter, its imports, or injected libraries.
RISKY_ENV_RE = re.compile(r"(PATH|PYTHON[A-Za-z0-9_]*|LD_[A-Za-z0-9_]+|DYLD_[A-Za-z0-9_]+)=")
# Builtins and reserved words have no file to verify.
SHELL_BUILTINS = frozenset({
"cd", "exec", "source", ".", "export", "eval", "set", "unset", "true", "false", ":",
"[", "[[", "((", "test", "echo", "printf", "exit", "return", "local", "declare",
"typeset", "readonly", "shift", "trap", "builtin", "command", "type", "wait", "alias",
"unalias", "read", "ulimit", "umask", "pushd", "popd", "hash", "getopts", "let", "shopt",
"for", "case", "select", "function", "in", "}", ")", "fi", "done", "esac",
})
# Reserved words that introduce the next command word.
COMMAND_PREFIX_WORDS = frozenset({"!", "{", "(", "if", "then", "else", "elif", "do", "while", "until"})
CONTROL_OPERATORS = frozenset({";", "&&", "||", "|", "&", ";;", "|&"})
REDIRECT_OPERATORS = frozenset({"<", ">", ">>", "<<", "<<-", "<<<", "<>", ">|", "&>", "&>>", ">&", "<&"})
ENV_FLAGS = frozenset({"-i", "--ignore-environment", "-0", "--null", "-v", "--debug", "--"})
MAX_FILE_BYTES = 2_000_000
MAX_CONTEXT_PROJECT_FILES = 50_000
MAX_CONTEXT_MATCH_EVALUATIONS = 2_000_000
_AUDIT_ROOT: Optional[Path] = None
_AUDIT_HOME: Optional[Path] = None
_TRUSTED_SCRIPT_ROOT = Path(__file__).resolve().parent
def contained(path: Path, root: Path) -> bool:
try:
path.relative_to(root)
return True
except ValueError:
return False
def sensitive_path(path: Path, home: Path) -> bool:
for protected in (
home / ".ssh",
home / ".aws",
home / ".gnupg",
home / ".config" / "gh",
):
if path == protected or contained(path, protected):
return True
for part in path.parts:
lowered = part.lower()
if lowered == "secrets":
return True
if "credential" in lowered:
return True
if lowered == ".env" or lowered.startswith(".env."):
return True
return False
def audit_scope(path: Path) -> Optional[Path]:
absolute = path if path.is_absolute() else Path.cwd() / path
for root in (_AUDIT_ROOT, _AUDIT_HOME, _TRUSTED_SCRIPT_ROOT):
if root is not None and contained(absolute, root):
return root
return None
def resolve_audit_file(path: Path) -> Optional[Path]:
scope = audit_scope(path)
if scope is None:
return None
absolute = path if path.is_absolute() else Path.cwd() / path
home = _AUDIT_HOME or Path.home().resolve()
if any(ord(char) < 32 or ord(char) == 127 for char in str(absolute)):
return None
if sensitive_path(absolute, home):
return None
try:
resolved = path.resolve(strict=True)
except OSError:
return None
if not contained(resolved, scope) or sensitive_path(resolved, home):
return None
return resolved if resolved.is_file() else None
def resolve_audit_dir(path: Path) -> Optional[Path]:
scope = audit_scope(path)
if scope is None:
return None
absolute = path if path.is_absolute() else Path.cwd() / path
home = _AUDIT_HOME or Path.home().resolve()
if any(ord(char) < 32 or ord(char) == 127 for char in str(absolute)):
return None
if sensitive_path(absolute, home):
return None
try:
resolved = path.resolve(strict=True)
except OSError:
return None
if not contained(resolved, scope) or sensitive_path(resolved, home):
return None
return resolved if resolved.is_dir() else None
def rel(path: Path, root: Path) -> str:
try:
value = path.resolve().relative_to(root).as_posix()
except ValueError:
value = path.as_posix()
return safe_label(value)
def safe_label(value: str, limit: int = 500) -> str:
if any(ord(char) < 32 or ord(char) == 127 for char in value):
value = json.dumps(value, ensure_ascii=False)
return value if len(value) <= limit else f"{value[: limit - 3]}..."
def read_bytes(path: Path, limit: Optional[int] = None) -> bytes:
resolved = resolve_audit_file(path)
if resolved is None:
return b""
byte_limit = limit or MAX_FILE_BYTES
try:
flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
descriptor = os.open(resolved, flags)
except OSError:
return b""
try:
chunks: list[bytes] = []
remaining = byte_limit
while remaining:
chunk = os.read(descriptor, min(65_536, remaining))
if not chunk:
break
chunks.append(chunk)
remaining -= len(chunk)
return b"".join(chunks)
except OSError:
return b""
finally:
os.close(descriptor)
def read(path: Path, limit: Optional[int] = None) -> str:
return read_bytes(path, limit).decode("utf-8", errors="replace")
def yes(path: Path) -> str:
return "yes" if resolve_audit_file(path) is not None else "no"
def print_list(
title: str,
items: list[str],
empty: str = "(none)",
limit: Optional[int] = None,
) -> None:
print(f"{title}:")
shown = items if limit is None else items[:limit]
if not shown:
print(f" {empty}")
return
for item in shown:
print(f" {safe_label(item)}")
if limit is not None and len(items) > limit:
print(f" ... {len(items) - limit} more")
def load_json(path: Path) -> tuple[Optional[object], Optional[str]]:
if resolve_audit_file(path) is None:
return None, None
try:
return json.loads(read(path)), None
except json.JSONDecodeError as exc:
return None, f"{path.name}: invalid JSON at line {exc.lineno}"
def redact_sensitive_entries(value: object, prefix: str = "") -> list[str]:
entries: list[str] = []
if isinstance(value, dict):
for key, child in value.items():
child_prefix = f"{prefix}.{key}" if prefix else str(key)
if SENSITIVE_RE.search(str(key)):
entries.append(f"{safe_label(child_prefix)}=[REDACTED]")
continue
entries.extend(redact_sensitive_entries(child, child_prefix))
elif isinstance(value, list):
for index, child in enumerate(value):
entries.extend(redact_sensitive_entries(child, f"{prefix}[{index}]"))
return entries
def string_list(value: object) -> list[str]:
if isinstance(value, list):
return [
safe_label(str(item)) if not SENSITIVE_RE.search(str(item)) else "[REDACTED]"
for item in value
]
if isinstance(value, dict):
return sorted(safe_label(str(key)) for key in value)
if isinstance(value, str):
return ["[REDACTED]" if SENSITIVE_RE.search(value) else safe_label(value)]
return []
def skill_root_count(path: Path, include_root_md: bool) -> int:
directory = resolve_audit_dir(path)
if directory is None:
return 0
count = sum(
1
for candidate in directory.rglob("SKILL.md")
if resolve_audit_file(candidate) is not None
)
if include_root_md:
count += sum(
1
for candidate in directory.glob("*.md")
if candidate.name != "SKILL.md" and resolve_audit_file(candidate) is not None
)
return count
def same_physical_file(left: Path, right: Path) -> bool:
left_resolved = resolve_audit_file(left)
right_resolved = resolve_audit_file(right)
if left_resolved is None or right_resolved is None:
return False
try:
return left_resolved.samefile(right_resolved)
except OSError:
return False
def unique_physical_files(paths: list[Path]) -> list[Path]:
unique: list[Path] = []
seen: set[tuple[int, int]] = set()
for path in paths:
canonical = resolve_audit_file(path)
if canonical is None:
continue
try:
stat = canonical.stat()
except OSError:
continue
identity = (stat.st_dev, stat.st_ino)
if identity in seen:
continue
seen.add(identity)
unique.append(path)
return unique
def project_instruction_files(root: Path) -> list[Path]:
files = [
root / "AGENTS.md",
root / "CLAUDE.md",
root / ".github" / "copilot-instructions.md",
root / "GEMINI.md",
]
instructions_dir = root / ".github" / "instructions"
if resolve_audit_dir(instructions_dir) is not None:
files.extend(sorted(instructions_dir.glob("*.md")))
return unique_physical_files(files)
WALK_EXCLUDED_DIRS = {
".git", ".hg", ".svn", "node_modules", "dist", "build", ".next",
"__pycache__", ".venv", "venv", "target", "coverage", ".cache",
".pytest_cache", ".mypy_cache", ".ruff_cache", "Pods", "Carthage",
".swiftpm", ".gradle",
}
PROJECT_INSTRUCTION_MODES = (
"claude-md",
"claude-md-or-agents-md",
"claude-md-and-agents-md",
"managed-only",
)
def project_instructions_mode(settings_path: Path) -> str:
"""Which files Claude Code loads as project instructions.
The built-in `cc-plugin-agents-md` mod (`agents-md` before v2.1.285)
decides whether an `AGENTS.md` counts. Since v2.1.277 it is on by default
in `claude-md-or-agents-md`: a root `CLAUDE.md` wins, otherwise
`AGENTS.md` loads. `pluginConfigs` only changes that mode, and disabling
the plugin in `enabledPlugins` turns `AGENTS.md` off altogether.
"""
default = "claude-md-or-agents-md"
value, _ = load_json(settings_path)
if not isinstance(value, dict):
return default
ids = ("cc-plugin-agents-md@builtin", "agents-md@builtin")
enabled = value.get("enabledPlugins")
if isinstance(enabled, dict) and any(enabled.get(key) is False for key in ids):
return "claude-md"
configs = value.get("pluginConfigs")
if not isinstance(configs, dict):
return default
for key in ids:
entry = configs.get(key)
options = entry.get("options") if isinstance(entry, dict) else None
mode = options.get("instructionFiles") if isinstance(options, dict) else None
if mode in PROJECT_INSTRUCTION_MODES:
return mode
return default
def nested_agents_files(root: Path) -> list[Path]:
"""`AGENTS.md` below the root, which only some runtimes walk into."""
resolved = resolve_audit_dir(root)
if resolved is None:
return []
found: list[Path] = []
for path in sorted(resolved.rglob("AGENTS.md")):
if path.parent == resolved:
continue
if any(part.startswith(".") or part in WALK_EXCLUDED_DIRS for part in path.relative_to(resolved).parts[:-1]):
continue
found.append(path)
return unique_physical_files(found)
def claude_delegates_to_agents(path: Path) -> bool:
text = read(path, 20_000)
if not text:
return False
meaningful = [
line.strip()
for line in text.splitlines()
if line.strip() and not line.strip().startswith("#")
]
return any("AGENTS.md" in line for line in meaningful)
def has_operational_rules(path: Path) -> bool:
text = read(path, 40_000)
if not text:
return False
return len(set(m.group(1).lower() for m in OPERATIONAL_RULE_RE.finditer(text))) >= 2
def looks_identity_only(path: Path) -> bool:
text = read(path, 40_000)
if not text:
return False
return "nian-identity:start" in text and not has_operational_rules(path)
def rule_paths(text: str) -> list[str]:
if not text.startswith("---"):
return []
lines = text.splitlines()
paths: list[str] = []
in_paths = False
for line in lines[1:]:
stripped = line.strip()
if stripped == "---":
break
if stripped == "paths:":
in_paths = True
continue
if in_paths and stripped.startswith("-"):
value = stripped[1:].strip().strip('"\'')
if value:
paths.append(value)
continue
if in_paths and stripped and not line.startswith((" ", "\t")):
in_paths = False
return paths
def selector_pattern(selector: str) -> re.Pattern[str]:
"""Compile Claude's slash-aware * / ** path glob subset."""
pattern = ["^"]
index = 0
while index < len(selector):
char = selector[index]
if char == "*":
if index + 1 < len(selector) and selector[index + 1] == "*":
if index + 2 < len(selector) and selector[index + 2] == "/":
pattern.append("(?:.*/)?")
index += 3
else:
pattern.append(".*")
index += 2
else:
pattern.append("[^/]*")
index += 1
elif char == "?":
pattern.append("[^/]")
index += 1
else:
pattern.append(re.escape(char))
index += 1
pattern.append("$")
return re.compile("".join(pattern))
def context_units(text: str) -> int:
"""Conservative language-neutral context estimate for rule budgeting."""
cjk_characters = len(CJK_CONTEXT_RE.findall(text))
non_cjk_words = len(CJK_CONTEXT_RE.sub(" ", text).split())
return non_cjk_words + cjk_characters
def project_relative_files(root: Path) -> tuple[list[str], bool]:
excluded = WALK_EXCLUDED_DIRS
paths: list[str] = []
for dirpath, dirnames, filenames in os.walk(root, followlinks=False):
current = Path(dirpath)
dirnames[:] = sorted(
name
for name in dirnames
if name not in excluded and not (current / name).is_symlink()
)
for filename in sorted(filenames):
path = current / filename
if path.is_symlink() or not path.is_file():
continue
try:
relative = path.relative_to(root).as_posix()
except ValueError:
continue
if any(ord(char) < 32 or ord(char) == 127 for char in relative):
continue
paths.append(relative)
if len(paths) >= MAX_CONTEXT_PROJECT_FILES:
return paths, True
return paths, False
def summarize_rule_context(
rule_roots: list[tuple[str, Path]], root: Path
) -> tuple[str, list[str]]:
path_counts: Counter[str] = Counter()
path_words: Counter[str] = Counter()
path_units: Counter[str] = Counter()
rule_entries: list[tuple[str, int, int, list[re.Pattern[str]]]] = []
scoped_files = 0
scoped_words = 0
scoped_units = 0
always_files = 0
always_words = 0
always_units = 0
always_by_scope: Counter[str] = Counter()
rule_files: list[tuple[str, Path]] = []
seen_rules: set[Path] = set()
for scope, rule_root in rule_roots:
if resolve_audit_dir(rule_root) is None:
continue
for path in sorted(rule_root.glob("*.md")):
canonical = resolve_audit_file(path)
if canonical is None or canonical in seen_rules:
continue
seen_rules.add(canonical)
rule_files.append((scope, path))
selector_count = 0
for scope, path in rule_files:
text = read(path)
words = len(text.split())
units = context_units(text)
paths = rule_paths(text)
if paths:
scoped_files += 1
scoped_words += words
scoped_units += units
selector_count += len(paths)
rule_entries.append(
(
f"{scope}:{path.name}",
words,
units,
[selector_pattern(selector) for selector in paths],
)
)
for selector in paths:
path_counts[selector] += 1
path_words[selector] += words
path_units[selector] += units
else:
always_files += 1
always_words += words
always_units += units
always_by_scope[scope] += 1
ranked = sorted(
path_counts,
key=lambda selector: (path_units[selector], path_counts[selector], selector),
reverse=True,
)
effective_loads: list[tuple[int, int, str, list[str]]] = []
project_files, project_files_truncated = project_relative_files(root)
match_evaluations = 0
match_budget_exhausted = False
matched_rules: set[str] = set()
for relative in project_files:
matching: list[tuple[str, int, int]] = []
for name, words, units, patterns in rule_entries:
matched = False
for pattern in patterns:
if match_evaluations >= MAX_CONTEXT_MATCH_EVALUATIONS:
match_budget_exhausted = True
break
match_evaluations += 1
if pattern.fullmatch(relative):
matched = True
break
if match_budget_exhausted:
break
if matched:
matching.append((name, words, units))
matched_rules.add(name)
if match_budget_exhausted:
break
if matching:
effective_loads.append(
(
sum(units for _, _, units in matching),
sum(words for _, words, _ in matching),
relative,
[name for name, _, _ in matching],
)
)
effective_loads.sort(key=lambda item: (item[0], item[2]), reverse=True)
# A project rule whose selectors match no project file never loads. Global rules are
# exempt (they target other projects too), and a truncated walk proves nothing.
dead_rules: list[str] = []
if not project_files_truncated and not match_budget_exhausted:
dead_rules = sorted(
name
for name, _, _, _ in rule_entries
if name.startswith("project:") and name not in matched_rules
)
findings: list[str] = []
if dead_rules:
findings.append(
"path rules match no project file and never load: "
+ ", ".join(safe_label(name) for name in dead_rules[:10])
)
oversized_files: list[str] = []
for scope, path in rule_files:
text = read(path)
words = len(text.split())
units = context_units(text)
if units > 5_000:
oversized_files.append(
f"{scope}:{path.name} words={words} context_units={units}"
)
if always_units > 5_000:
findings.append(
"always-loaded rules exceed 5000 context units: "
f"words={always_words} context_units={always_units}"
)
if ranked and path_units[ranked[0]] > 10_000:
findings.append(
"one path selector loads more than 10000 context units: "
f"{ranked[0]} words={path_words[ranked[0]]} "
f"context_units={path_units[ranked[0]]}"
)
if effective_loads and effective_loads[0][0] > 10_000:
units, words, relative, matching_rules = effective_loads[0]
findings.append(
"one project path loads more than 10000 effective context units: "
f"{relative} words={words} context_units={units} "
f"rules={','.join(matching_rules)}"
)
if oversized_files:
findings.append("oversized path rules: " + ", ".join(oversized_files[:5]))
if project_files_truncated:
findings.append(
f"project path inventory exceeded {MAX_CONTEXT_PROJECT_FILES} files"
)
if match_budget_exhausted:
findings.append(
"path rule matching exceeded "
f"{MAX_CONTEXT_MATCH_EVALUATIONS} evaluations"
)
status = "WARN" if findings else "PASS"
lines = [
"=== PATH-SCOPED CONTEXT ===",
f"path_context_status: {status}",
f"path_context_rule_roots_scanned: {len(rule_roots)}",
f"path_context_selectors: {selector_count}",
f"path_context_project_files: {len(project_files)}",
f"path_context_project_files_truncated: {'yes' if project_files_truncated else 'no'}",
f"path_context_match_evaluations: {match_evaluations}",
f"path_context_match_budget_exhausted: {'yes' if match_budget_exhausted else 'no'}",
f"path_scoped_rule_files: {scoped_files}",
f"path_scoped_rule_words: {scoped_words}",
f"path_scoped_rule_context_units: {scoped_units}",
f"path_rules_matching_nothing: {len(dead_rules)}",
f"always_loaded_rule_files: {always_files}",
f"always_loaded_rule_words: {always_words}",
f"always_loaded_rule_context_units: {always_units}",
"always_loaded_rule_scope: "
+ " ".join(f"{scope}={always_by_scope[scope]}" for scope, _ in rule_roots),
"largest_path_triggers:",
]
if not ranked:
lines.append(" (none)")
else:
for selector in ranked[:10]:
lines.append(
f" selector={safe_label(selector)} files={path_counts[selector]} "
f"combined_words={path_words[selector]} "
f"combined_context_units={path_units[selector]}"
)
lines.append("largest_effective_paths:")
if not effective_loads:
lines.append(" (none)")
else:
for units, words, relative, matching_rules in effective_loads[:10]:
lines.append(
f" path={safe_label(relative)} words={words} "
f"context_units={units} "
f"rules={safe_label(','.join(matching_rules))}"
)
lines.append("path_context_findings:")
lines.extend(f" {item}" for item in (findings or ["(none)"]))
return status, lines
def skill_name(path: Path) -> str:
for line in read(path, 8_000).splitlines()[:40]:
match = re.match(r"^name:\s*[\"']?([^\"']+?)[\"']?\s*$", line.strip())
if match:
return safe_label(match.group(1).strip())
return ""
def display_path(path: Path, root: Path, home: Path) -> str:
for base, prefix in ((root, "project:/"), (home, "~/")):
try:
return safe_label(prefix + path.relative_to(base).as_posix())
except ValueError:
continue
return safe_label(path.as_posix())
def broken_symlink(path: Path) -> bool:
if not path.is_symlink():
return False
try:
path.resolve(strict=True)
except FileNotFoundError:
return True
except (OSError, RuntimeError):
pass
return False
def candidate_skill_files(root: Path, home: Path) -> tuple[list[Path], int, list[Path]]:
roots = [
root / ".claude" / "skills",
root / ".agents" / "skills",
root / ".codex" / "skills",
home / ".claude" / "skills",
home / ".agents" / "skills",
home / ".codex" / "skills",
]
candidates: list[Path] = []
broken_links: set[Path] = set()
repository_roots: set[Path] = set()
for skill_root in roots:
if broken_symlink(skill_root):
broken_links.add(skill_root)
if resolve_audit_dir(skill_root) is None:
continue
candidates.extend(skill_root.glob("*/SKILL.md"))
for child in skill_root.iterdir():
if broken_symlink(child):
broken_links.add(child)
continue
if resolve_audit_dir(child) is not None and broken_symlink(child / "SKILL.md"):
broken_links.add(child / "SKILL.md")
if not child.is_symlink():
continue
try:
resolved = child.resolve(strict=True)
except OSError:
continue
if resolve_audit_dir(resolved) is None:
continue
if (
resolve_audit_dir(resolved / "skills") is not None
or resolve_audit_dir(resolved / "plugins") is not None
):
repository_roots.add(resolved)
for repository in repository_roots:
candidates.extend(repository.glob("skills/*/SKILL.md"))
unique: dict[Path, Path] = {}
mirrors_collapsed = 0
for path in candidates:
canonical = resolve_audit_file(path)
if canonical is None:
continue
if canonical in unique:
mirrors_collapsed += 1
continue
unique[canonical] = path
return sorted(unique.values()), mirrors_collapsed, sorted(broken_links)
def skill_runtime(path: Path, root: Path, home: Path) -> str:
for base, runtime in (
(root / ".claude" / "skills", "claude"),
(home / ".claude" / "skills", "claude"),
(root / ".agents" / "skills", "agents"),
(home / ".agents" / "skills", "agents"),
(root / ".codex" / "skills", "codex"),
(home / ".codex" / "skills", "codex"),
):
try:
path.relative_to(base)
return runtime
except ValueError:
continue
return "other"
def summarize_skill_duplicates(root: Path, home: Path) -> tuple[str, list[str]]:
by_name: dict[str, list[tuple[Path, str, str]]] = defaultdict(list)
skill_files, mirrors_collapsed, broken_links = candidate_skill_files(root, home)
for path in skill_files:
name = skill_name(path)
if not name:
continue
try:
raw = read_bytes(path)
if not raw:
continue
digest = hashlib.sha256(raw).hexdigest()
except OSError:
continue
by_name[name].append((path, digest, skill_runtime(path, root, home)))
duplicate_lines: list[str] = []
cross_runtime_lines: list[str] = []
cross_runtime_conflicts: list[str] = []
for name, entries in sorted(by_name.items()):
if len(entries) < 2:
continue
by_runtime: dict[str, list[tuple[Path, str]]] = defaultdict(list)
for path, digest, runtime in entries:
by_runtime[runtime].append((path, digest))
same_runtime = {
runtime: runtime_entries
for runtime, runtime_entries in by_runtime.items()
if len(runtime_entries) > 1
}
if same_runtime:
flattened = [item for group in same_runtime.values() for item in group]
digest_counts = Counter(digest for _, digest in flattened)
exact_duplicate = any(count > 1 for count in digest_counts.values())
kind = "exact-copy" if exact_duplicate else "name-collision"
surfaces = ", ".join(
display_path(path, root, home) for path, _ in flattened[:6]
)
duplicate_lines.append(f"{name}: kind={kind} surfaces={surfaces}")
elif len(by_runtime) > 1:
runtimes = ",".join(sorted(by_runtime))
digests = {digest for _path, digest, _runtime in entries}
content = "identical" if len(digests) == 1 else "divergent"
line = f"{name}: runtimes={runtimes} content={content}"
cross_runtime_lines.append(line)
if content == "divergent":
cross_runtime_conflicts.append(line)
source_skill_files = (
unique_physical_files(list((root / "skills").glob("*/SKILL.md")))
if resolve_audit_dir(root / "skills") is not None
else []
)
lines = [
"=== SKILL ROUTING DUPLICATES ===",
f"skill_files_scanned: {sum(len(entries) for entries in by_name.values())}",
f"mirrored_skill_files_collapsed: {mirrors_collapsed}",
f"source_skill_files_scanned: {len(source_skill_files)}",
f"duplicate_skill_names: {len(duplicate_lines)}",
"duplicate_skills:",
]
lines.extend(f" {line}" for line in (duplicate_lines or ["(none)"]))
lines.append(f"cross_runtime_shared_skill_names: {len(cross_runtime_lines)}")
lines.append("cross_runtime_skills:")
lines.extend(f" {line}" for line in (cross_runtime_lines or ["(none)"]))
lines.append(f"cross_runtime_conflicts: {len(cross_runtime_conflicts)}")
lines.append(f"broken_skill_links: {len(broken_links)}")
if broken_links:
lines.append("broken_skill_link_paths:")
lines.extend(f" {display_path(path, root, home)}" for path in broken_links)
return ("WARN" if duplicate_lines or cross_runtime_conflicts or broken_links else "PASS"), lines
def parse_codex_config(
path: Path,
) -> tuple[dict[str, str], list[str], list[str], list[str], list[str]]:
projects: dict[str, str] = {}
features: list[str] = []
plugins: list[str] = []
marketplaces: list[str] = []
redacted: list[str] = []
if resolve_audit_file(path) is None:
return projects, features, plugins, marketplaces, redacted
section = ""
for raw in read(path).splitlines():
line = raw.strip()
if not line or line.startswith("#"):
continue
project_match = PROJECT_RE.match(line)
if project_match:
section = f'projects."{project_match.group(1)}"'
projects.setdefault(project_match.group(1), "")
continue
table_match = TABLE_RE.match(line)
if table_match:
section = table_match.group(1)
marketplace_match = re.match(r'marketplaces\.([A-Za-z0-9_.@-]+)$', section)
plugin_match = re.fullmatch(r'plugins\.(?:"([^"]+)"|([A-Za-z0-9_@-]+))', section)
if marketplace_match:
marketplaces.append(marketplace_match.group(1))
if plugin_match:
plugins.append(plugin_match.group(1) or plugin_match.group(2))
continue
if SENSITIVE_RE.search(line):
key = line.split("=", 1)[0].strip() if "=" in line else "sensitive"
redacted.append(f"{key}=[REDACTED]")
continue
if "=" not in line:
continue
key, value = [part.strip() for part in line.split("=", 1)]
plugin_match = re.fullmatch(r'plugins\.(?:"([^"]+)"|([A-Za-z0-9_@-]+))', section)
if plugin_match and key == "enabled":
name = plugin_match.group(1) or plugin_match.group(2)
if value.split("#", 1)[0].strip() == "false" and name in plugins:
plugins.remove(name)
if section == "features" and value.split("#", 1)[0].strip().strip('"').lower() == "true":
features.append(key)
elif section.startswith('projects."') and key == "trust_level":
project = section[len('projects."'): -1]
projects[project] = value.strip('"')
return (
projects,
sorted(set(features)),
sorted(set(plugins)),
sorted(set(marketplaces)),
sorted(set(redacted)),
)
def shell_tokens(command: str) -> list[str]:
try:
lexer = shlex.shlex(command, posix=True, punctuation_chars=True)
lexer.whitespace_split = True
return list(lexer)
except ValueError:
return []
def command_word_index(tokens: list[str], start: int = 0) -> int:
"""Return the executed word of the simple command at start, or -1 for an unmodeled prefix.
Skips assignments, redirections, reserved prefix words, and env, exec and command
prefixes in any order. An index at the end or on a control operator means no word.
"""
index = start
while index < len(tokens):
token = tokens[index]
if token in CONTROL_OPERATORS:
return index
if ASSIGNMENT_RE.fullmatch(token) or token in COMMAND_PREFIX_WORDS:
index += 1
elif token in REDIRECT_OPERATORS:
index += 2
elif token.isdigit() and index + 1 < len(tokens) and tokens[index + 1] in REDIRECT_OPERATORS:
index += 3
elif Path(token).name == "env":
index += 1
while index < len(tokens) and tokens[index].startswith("-"):
flag = tokens[index]
if flag in {"-u", "--unset"}:
index += 2
elif flag in ENV_FLAGS or flag.startswith("--unset="):
index += 1
else:
return -1
elif token == "exec":
index += 1
while index < len(tokens) and tokens[index].startswith("-"):
flag = tokens[index]
if flag == "-a":
index += 2
elif set(flag[1:]) <= {"c", "l"}:
index += 1
else:
return -1
elif token == "time":
index += 1
while index < len(tokens) and tokens[index] in {"-p", "--"}:
index += 1
elif token == "command" and index + 1 < len(tokens) and tokens[index + 1] == "-p":
index += 2
elif token == "command" and index + 1 < len(tokens) and not tokens[index + 1].startswith("-"):
index += 1
elif token.startswith("-"):
return -1
else:
return index
return index
def hook_command_words(tokens: list[str]) -> list[Optional[str]]:
"""Executed word of each simple command in a hook; None marks an unmodeled prefix."""
words: list[Optional[str]] = []
index = 0
while index < len(tokens):
word_index = command_word_index(tokens, index)
if word_index < 0:
words.append(None)
word_index = index
elif word_index < len(tokens) and tokens[word_index] not in CONTROL_OPERATORS:
words.append(tokens[word_index])
while word_index < len(tokens) and tokens[word_index] not in CONTROL_OPERATORS:
word_index += 1
index = word_index + 1
return words
def runtime_inventory(root: Path, home: Path) -> list[str]:
"""Inspect configured sources without starting servers or exposing arguments."""
lines = ["=== RUNTIME CONFIGURATION ===",
"runtime_probe: static; no servers started",
"plugin_mcp_coverage: Claude user registry; Codex plugin state not inspected"]
servers: dict[str, dict[str, tuple[str, dict]]] = {"claude": {}, "codex": {}}
sources = [
("claude:user", home / ".claude.json"),
("claude:project", root / ".mcp.json"),
("claude:global", home / ".claude" / "settings.json"),
("claude:shared", root / ".claude" / "settings.json"),
("claude:local", root / ".claude" / "settings.local.json"),
("codex:global", home / ".codex" / "hooks.json"),
]
def executable_state(command: object) -> str:
if not isinstance(command, str) or not command:
return "remote"
if "$" in command:
return "unresolved"
if command.startswith("~/"):
path = home / command[2:]
elif Path(command).is_absolute():
path = Path(command)
elif "/" in command or "\\" in command:
return "relative; runtime working directory required"
else:
return "found" if shutil.which(command) else "missing"
return "found" if path.is_file() and os.access(path, os.X_OK) else "missing"
settings, _ = load_json(home / ".claude" / "settings.json")
installed, _ = load_json(home / ".claude" / "plugins" / "installed_plugins.json")
if isinstance(settings, dict) and isinstance(installed, dict):
registry = installed.get("plugins", {})
enabled_plugins = settings.get("enabledPlugins", {})
for name, enabled in enabled_plugins.items() if isinstance(enabled_plugins, dict) else []:
if enabled is not True or not isinstance(registry, dict):
continue
entries = registry.get(name, [])
for entry in entries if isinstance(entries, list) else []:
if isinstance(entry, dict) and entry.get("scope") == "user" and isinstance(entry.get("installPath"), str):
sources.append(("claude:plugin:" + str(name), Path(entry["installPath"]) / ".mcp.json"))
# Claude resolves same-name MCP servers as local > project > user.
precedence = {"claude:user": 1, "claude:project": 2, "claude:local-project": 3}
disabled_names: set[str] = set()
disabled_mcpjson: set[str] = set()
approved_mcpjson: set[str] = set()
approve_all_mcpjson = False
user_servers: dict[str, dict] = {}
# Claude names plugin servers plugin:<plugin>:<server>; that name is what disable lists hold.
plugin_runtime_names: dict[str, str] = {}
def listed(name: Optional[str], names: set[str]) -> bool:
# Approval and disable lists may hold the normalized form Claude shows in /mcp.
if name is None:
return False
return name in names or re.sub(r"[^A-Za-z0-9_-]", "_", name) in {
re.sub(r"[^A-Za-z0-9_-]", "_", item) for item in names
}
def add_claude_server(name: str, label: str, config: dict) -> None:
if label == "claude:user":
user_servers[name] = config
existing = servers["claude"].get(name)
if existing and precedence.get(existing[0], 0) > precedence.get(label, 0) > 0:
return
servers["claude"][name] = (label, config)
for label, path in sources:
data, error = load_json(path)
if error:
lines.append(f"{label} config=invalid")
if not isinstance(data, dict):
continue
if label in {"claude:user", "claude:project"} or ":plugin:" in label:
mappings = data.get("mcpServers", data if ":plugin:" in label else {})
for name, config in mappings.items() if isinstance(mappings, dict) else []:
if isinstance(config, dict):
server_name = label + ":" + str(name) if ":plugin:" in label else str(name)
if ":plugin:" in label:
plugin = label.split(":plugin:", 1)[1].split("@", 1)[0]
plugin_runtime_names[server_name] = f"plugin:{plugin}:{name}"
add_claude_server(server_name, label, config)
elif "mcpServers" in data:
# Claude reads MCP servers from ~/.claude.json, .mcp.json and plugins, never settings files.
lines.append(f"{label} mcp_servers=ignored; not an MCP source")
approval_sources: list[dict] = []
if label in {"claude:global", "claude:shared", "claude:local"}:
approval_sources.append(data)
if label == "claude:user":
projects = data.get("projects", {})
local = projects.get(str(root), {}) if isinstance(projects, dict) else {}
local = local if isinstance(local, dict) else {}
mappings = local.get("mcpServers", {})
for name, config in mappings.items() if isinstance(mappings, dict) else []:
if isinstance(config, dict):
add_claude_server(str(name), "claude:local-project", config)
names = local.get("disabledMcpServers", [])
if isinstance(names, list):
disabled_names.update(n for n in names if isinstance(n, str))
approval_sources.append(local)
for source in approval_sources:
for key, target in (("disabledMcpjsonServers", disabled_mcpjson),
("enabledMcpjsonServers", approved_mcpjson)):
names = source.get(key, [])
if isinstance(names, list):
target.update(n for n in names if isinstance(n, str))
if source.get("enableAllProjectMcpServers") is True:
approve_all_mcpjson = True
hooks = data.get("hooks", {})
if not isinstance(hooks, dict):
continue
for event, groups in hooks.items():
for group in groups if isinstance(groups, list) else []:
if not isinstance(group, dict):
continue
handlers = group.get("hooks", [])
for handler in handlers if isinstance(handlers, list) else []:
if not isinstance(handler, dict):
continue
kind = handler.get("type", "unknown")
lines.append(f"{label} hook={safe_label(str(event))} type={safe_label(str(kind))}")
command = handler.get("command", "")
if kind == "command" and isinstance(command, str):
states: list[str] = []
for word in hook_command_words(shell_tokens(command)):
if word is None:
state = "unverified; unmodeled command prefix"
elif word in SHELL_BUILTINS or set(word) <= set("();<>|&"):
continue
else:
state = executable_state(word)
if state not in states:
states.append(state)
lines.append(f"{label} hook_executable={state}")
elif kind == "mcp_tool":
if not handler.get("server") or not handler.get("tool"):
lines.append(f"{label} mcp_hook=missing server or tool")
elif kind not in {"prompt", "agent", "http", "command"}:
lines.append(f"{label} hook_type=unverified")
# Codex runs without config.toml and still applies its default limit; no ~/.codex means no budget.
codex_config = home / ".codex" / "config.toml"
codex = {} if (home / ".codex").is_dir() else None
if codex is not None and codex_config.exists() and yes(codex_config) == "no":
codex = None
lines.append("codex_runtime_config: unavailable; config.toml is outside the audit scope")
elif yes(codex_config) == "yes":
codex = None
# TOML parsing is optional on Python 3.9/3.10; report the gap, never a false zero.
try:
import tomllib
except ImportError:
lines.append("codex_runtime_config: unavailable; Python 3.11+ TOML parser required")
else:
try:
codex = tomllib.loads(read(codex_config))
except (ValueError, OSError):
lines.append("codex_runtime_config: invalid")
if codex is not None:
mappings = codex.get("mcp_servers", {})
for name, config in mappings.items() if isinstance(mappings, dict) else []:
if isinstance(config, dict):
servers["codex"][name] = ("codex:user", config)
limit = codex.get("project_doc_max_bytes", 32768)
if isinstance(limit, int) and not isinstance(limit, bool) and limit > 0:
# Codex charges only project docs against the limit; ~/.codex/AGENTS.md is separate.
project_file = next((p for p in [root / "AGENTS.override.md", root / "AGENTS.md"] if read(p).strip()), None)
total = len(read_bytes(project_file)) if project_file else 0
lines.append("instruction_budget_scope: user config and current root project doc; global AGENTS.md not charged; ancestors, nested and fallback-name docs not included")
lines.append(f"project_instruction_bytes: {total}")
lines.append(f"project_instruction_limit: {limit}")
lines.append(f"project_instruction_limit_exceeded: {'yes' if total > limit else 'no'}")
for runtime, entries in servers.items():
for name, (label, config) in sorted(entries.items()):
# .mcp.json entries load only once approved; until then a same-name user server stays live.
rejected = label == "claude:project" and listed(name, disabled_mcpjson)
pending = (label == "claude:project" and not rejected
and not approve_all_mcpjson and not listed(name, approved_mcpjson))
if (rejected or pending) and name in user_servers:
label, config = "claude:user", user_servers[name]
rejected = pending = False
disabled = config.get("enabled") is False or config.get("disabled") is True
if runtime == "claude" and (
rejected
or listed(name, disabled_names)
or listed(plugin_runtime_names.get(name), disabled_names)
):
disabled = True
state = "disabled" if disabled else "pending" if pending else "enabled"
executable = "skipped" if disabled else executable_state(config.get("command"))
lines.append(f"{label} mcp={safe_label(name)} state={state} executable={executable}")
return lines
def permission_rules(data: object, key: str) -> list[str]:
if not isinstance(data, dict):
return []
permissions = data.get("permissions")
if not isinstance(permissions, dict):
return []
value = permissions.get(key)
if not isinstance(value, list):
return []
return [str(item) for item in value if isinstance(item, str)]
def parse_permission_rule(rule: str) -> tuple[str, str] | None:
match = re.fullmatch(r"([A-Za-z][A-Za-z0-9_]*)\((.*)\)", rule.strip())
if not match:
return None
return match.group(1), match.group(2).strip()
def normalized_rule_targets(rules: list[str], tool: str) -> list[str]:
targets: list[str] = []
for rule in rules:
parsed = parse_permission_rule(rule)
if parsed is None or parsed[0].lower() != tool.lower():
continue
targets.append(parsed[1].replace("\\", "/").lower())
return targets
def expand_permission_target(target: str, home: Path) -> str:
normalized = target.strip().replace("\\", "/")
home_text = home.resolve().as_posix().lower()
lowered = normalized.lower()
for prefix in ("${home}", "$home", "~"):
if lowered == prefix:
return home_text
if lowered.startswith(prefix + "/"):
return home_text + normalized[len(prefix):].lower()
return lowered
def target_covers_samples(target: str, home: Path, samples: tuple[str, ...]) -> bool:
pattern = expand_permission_target(target, home)
home_text = home.resolve().as_posix().lower()
return all(
fnmatch.fnmatchcase(f"{home_text}/{sample.lower()}", pattern)
for sample in samples
)
def target_covers_command(target: str, command: str) -> bool:
escaped = re.escape(command.lower())
return re.fullmatch(rf"{escaped}(?::\*|\s+\*.*)", target.strip()) is not None
def resolve_command_path(token: str, home: Path, project_root: Path) -> Path | None:
if token.startswith("~/"):
candidate = home / token[2:]
elif token.startswith("$HOME/"):
candidate = home / token[6:]
elif token.startswith("${HOME}/"):
candidate = home / token[8:]
else:
candidate = Path(token)
if not candidate.is_absolute():
candidate = project_root / candidate
return resolve_audit_file(candidate)
def resolve_hook_handler(command: str, home: Path, project_root: Path) -> Path | None:
tokens = shell_tokens(command)
command_index = command_word_index(tokens)
if command_index < 0 or command_index >= len(tokens) or tokens[command_index] in CONTROL_OPERATORS:
return None
# PATH, PYTHONPATH and loader overrides can swap what the hook runs, `!` can invert its exit
# status, and a redirect can cut it off from the tool input on stdin, so the floor credits none.
if any(
RISKY_ENV_RE.match(token) or token in COMMAND_PREFIX_WORDS or token in REDIRECT_OPERATORS
or token == "time"
for token in tokens[:command_index]
):
return None
executable = tokens[command_index]
if Path(executable).name in {"python", "python3"}:
safe_flags = {"-B", "-E", "-I", "-O", "-OO", "-P", "-q", "-s", "-S", "-u", "-v"}
for index, token in enumerate(tokens[command_index + 1 :], command_index + 1):
if token == "--":
continue
if token.startswith("-"):
if token not in safe_flags:
return None
continue
if index != len(tokens) - 1:
return None
resolved = resolve_command_path(token, home, project_root)
return resolved if resolved is not None and resolved.suffix == ".py" else None
return None
return None
def hook_handler_enforces_pipe_block(path: Path) -> bool:
canonical = Path(__file__).with_name("block-pipe-to-shell.py")
candidate_bytes = read_bytes(path)
canonical_bytes = read_bytes(canonical)
return bool(candidate_bytes) and candidate_bytes == canonical_bytes
def has_pretool_bash_hook(
data: object,
home: Path,
project_root: Path,
) -> bool:
if not isinstance(data, dict):
return False
hooks = data.get("hooks")
if not isinstance(hooks, dict):
return False
pretool = hooks.get("PreToolUse")
if not isinstance(pretool, list):
return False
for group in pretool:
if not isinstance(group, dict) or group.get("matcher") != "Bash":
continue
handlers = group.get("hooks")
if not isinstance(handlers, list):
continue
for handler in handlers:
if not isinstance(handler, dict) or handler.get("type") != "command":
continue
command = handler.get("command")
if not isinstance(command, str):
continue
path = resolve_hook_handler(command, home, project_root)
if path is not None and hook_handler_enforces_pipe_block(path):
return True
return False
def deny_category_status(
rules: list[str],
hook_present: bool,
home: Path,
) -> dict[str, bool]:
reads = normalized_rule_targets(rules, "Read")
bash = normalized_rule_targets(rules, "Bash")
return {
"ssh_directory": any(
target_covers_samples(target, home, (".ssh/id_key", ".ssh/config"))
for target in reads
),
"aws_directory": any(
target_covers_samples(target, home, (".aws/credentials", ".aws/config"))
for target in reads
),
"gnupg_directory": any(
target_covers_samples(
target,
home,
(".gnupg/private-keys-v1.d/key", ".gnupg/gpg.conf"),
)
for target in reads
),
"gh_directory": any(
target_covers_samples(
target,
home,
(".config/gh/hosts.yml", ".config/gh/config.yml"),
)
for target in reads
),
"env_files": any(
target_covers_samples(
target,
home,
("project/.env", "project/.env.local"),
)
for target in reads
),
"credential_files": any(
target_covers_samples(
target,
home,
("project/credentials.json", "project/service-credentials.txt"),
)
for target in reads
),
"secrets_directories": any(
target_covers_samples(
target,
home,
("project/secrets/token", "project/secrets/nested/key"),
)
for target in reads
),
"outbound_shell": all(
any(target_covers_command(target, command) for target in bash)
for command in ("ssh", "scp", "nc")
),
"pipe_to_shell": hook_present,
"git_reset_hard": any(
target_covers_command(target, "git reset --hard") for target in bash
),
}
def has_task_scoped_env_policy(paths: list[Path]) -> bool:
for path in paths:
text = read(path, 200_000).lower()
if ".env" not in text:
continue
if re.search(
r"task.scoped|current task|task needs|read when needed|"
r"当前任务|确需|外传|写出|不进产出|"
r"do not (?:print|output|commit|exfiltrate)",
text,
):
return True
return False
def summarize_claude_permissions(
global_path: Path,
shared_path: Path,
local_path: Path,
env_instruction_policy: bool,
) -> tuple[str, list[str], list[str]]:
sources = [
("global", global_path),
("shared", shared_path),
("local", local_path),
]
loaded: dict[str, object] = {}
errors: list[str] = []
for label, path in sources:
data, error = load_json(path)
if error:
errors.append(f"{label}: {error}")
loaded[label] = data
rules = {
label: {
key: permission_rules(loaded[label], key)
for key in ("allow", "deny", "ask")
}
for label, _path in sources
}
combined_allow = [
rule for label, _path in sources for rule in rules[label]["allow"]
]
combined_deny = [
rule for label, _path in sources for rule in rules[label]["deny"]
]
home = global_path.parent.parent
hook_present = any(
has_pretool_bash_hook(
loaded[label],
home,
path.parent.parent,
)
for label, path in sources
)
categories = deny_category_status(combined_deny, hook_present, home)
required_categories = {
name: present for name, present in categories.items() if name != "env_files"
}
missing = [name for name, present in required_categories.items() if not present]
env_policy_complete = categories["env_files"] or env_instruction_policy
if not env_policy_complete:
missing.append("env_policy")
broad_read_allow = any(
"**" in target
for target in normalized_rule_targets(combined_allow, "Read")
)
credential_floor = all(required_categories.values()) and env_policy_complete
settings_surface_present = any(yes(path) == "yes" for _label, path in sources)
findings: list[str] = list(errors)
if settings_surface_present and not credential_floor:
findings.append(
"configured global + shared project + local project deny floor is incomplete: "
+ ", ".join(missing)
)
lines = [
"=== CLAUDE PERMISSION SURFACE ===",
f"global_settings_json: {yes(global_path)}",
f"shared_project_settings_json: {yes(shared_path)}",
f"local_project_settings_json: {yes(local_path)}",
]
for label, _path in sources:
lines.extend(
f"{label}_{key}_count: {len(rules[label][key])}"
for key in ("allow", "deny", "ask")
)
lines.extend([
f"broad_read_allow_present: {'yes' if broad_read_allow else 'no'}",
f"pretool_pipe_to_shell_hook: {'yes' if hook_present else 'no'}",
f"env_instruction_policy: {'yes' if env_instruction_policy else 'no'}",
"configured_sensitive_deny_floor_complete: "
+ (
"not_applicable"
if not settings_surface_present
else ("yes" if credential_floor else "no")
),
])
lines.extend(
f"deny_{name}: {'yes' if present else 'no'}"
for name, present in categories.items()
)
lines.append("permission_findings:")
lines.extend(f" {item}" for item in (findings or ["(none)"]))
status = "WARN" if findings else "PASS"
return status, lines, findings
def project_trust(projects: dict[str, str], root: Path) -> str:
root_text = root.as_posix()
if root_text in projects:
return f"exact:{safe_label(projects[root_text] or 'configured')}"
candidates = []
for project, level in projects.items():
try:
project_path = Path(project).expanduser().resolve()
except OSError:
continue
if project_path == root:
return f"exact:{safe_label(level or 'configured')}"
try:
root.relative_to(project_path)
except ValueError:
continue
candidates.append(
(len(project_path.as_posix()), level or "configured", project_path.as_posix())
)
if candidates:
_, level, project = sorted(candidates, reverse=True)[0]
return f"inherited:{safe_label(level)} from {safe_label(project)}"
return "missing"
def summarize_pi_surface(root: Path, home: Path) -> tuple[str, list[str]]:
global_settings = home / ".pi" / "agent" / "settings.json"
project_settings = root / ".pi" / "settings.json"
settings_sources = [
("global_settings", global_settings),
("project_settings", project_settings),
]
configured_skills: list[str] = []
configured_packages: list[str] = []
redacted_entries: list[str] = []
findings: list[str] = []
malformed = False
for label, path in settings_sources:
data, error = load_json(path)
if error:
malformed = True
findings.append(error)
continue
if not isinstance(data, dict):
continue
configured_skills.extend(
f"{label}.skills: {item}" for item in string_list(data.get("skills"))
)
configured_packages.extend(
f"{label}.packages: {item}" for item in string_list(data.get("packages"))
)
redacted_entries.extend(
f"{label}.{item}" for item in redact_sensitive_entries(data)
)
package_path = root / "package.json"
package_pi_skills: list[str] = []
data, error = load_json(package_path)
if error:
findings.append(error)
elif isinstance(data, dict):
pi_manifest = data.get("pi")
if isinstance(pi_manifest, dict):
package_pi_skills = string_list(pi_manifest.get("skills"))
pi_skill_dirs = [
("global_pi_skill_roots", home / ".pi" / "agent" / "skills", True),
("project_pi_skill_roots", root / ".pi" / "skills", True),
("global_agents_skill_roots", home / ".agents" / "skills", False),
("project_agents_skill_roots", root / ".agents" / "skills", False),
]
skill_counts = [
f"{label}: {skill_root_count(path, include_root_md)}"
for label, path, include_root_md in pi_skill_dirs
]
has_pi_surface = (
yes(global_settings) == "yes"
or yes(project_settings) == "yes"
or bool(package_pi_skills)
or any(not line.endswith(": 0") for line in skill_counts)
or bool(configured_skills)
or bool(configured_packages)
)
if not has_pi_surface:
findings.append("no Pi settings, package manifest, or skill directories found")
status = "WARN" if malformed else "PASS"
lines = [
"=== PI SURFACE ===",
f"pi_status: {status}",
f"global_settings_json: {yes(global_settings)}",
f"project_settings_json: {yes(project_settings)}",
f"package_json: {yes(package_path)}",
]
lines.extend(skill_counts)
lines.append("package_pi_skills:")
lines.extend(f" {item}" for item in (package_pi_skills or ["(none)"]))
lines.append("configured_skills:")
lines.extend(f" {item}" for item in (configured_skills or ["(none)"]))
lines.append("configured_packages:")
lines.extend(f" {item}" for item in (configured_packages or ["(none)"]))
lines.append("redacted_pi_entries:")
lines.extend(f" {item}" for item in (redacted_entries or ["(none)"]))
lines.append("pi_findings:")
lines.extend(f" {item}" for item in (findings or ["(none)"]))
return status, lines
def main() -> int:
global _AUDIT_ROOT, _AUDIT_HOME
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("root", nargs="?", default=".", help="Repo root (default: cwd)")
parser.add_argument(
"mode", nargs="?", default="summary", choices=("summary", "deep"),
help="Output detail level",
)
args = parser.parse_args()
root = Path(args.root).resolve()
mode = args.mode
home = Path(os.environ.get("HOME", str(Path.home()))).expanduser().resolve()
_AUDIT_ROOT = root
_AUDIT_HOME = home
if not root.is_dir():
print(f"Repo root not found: {safe_label(root.as_posix())}", file=sys.stderr)
return 2
instruction_files = project_instruction_files(root)
agents = root / "AGENTS.md"
claude = root / "CLAUDE.md"
claude_aliases_agents = (
yes(agents) == "yes" and yes(claude) == "yes" and same_physical_file(agents, claude)
)
claude_delegates = claude_aliases_agents or claude_delegates_to_agents(claude)
github_instructions_dir = root / ".github" / "instructions"
github_instruction_count = (
len(unique_physical_files(list(github_instructions_dir.glob("*.md"))))
if resolve_audit_dir(github_instructions_dir) is not None else 0
)
instruction_findings: list[str] = []
if not instruction_files:
instruction_findings.append("no project agent instruction files")
if yes(agents) == "yes" and yes(claude) == "yes" and not claude_delegates:
claude_lines = len(read(claude).splitlines())
agents_lines = len(read(agents).splitlines())
if claude_lines > 20 and agents_lines > 20:
instruction_findings.append(
"AGENTS.md and CLAUDE.md both contain substantial guidance without delegation"
)
global_codex_agents = home / ".codex" / "AGENTS.md"
codex_config = home / ".codex" / "config.toml"
projects, features, plugins, marketplaces, redacted = parse_codex_config(codex_config)
trust = project_trust(projects, root) if yes(codex_config) == "yes" else "unavailable"
codex_findings: list[str] = []
if yes(global_codex_agents) == "no" and yes(codex_config) == "no":
codex_findings.append("Codex surface not found")
elif yes(codex_config) == "yes" and trust == "missing":
codex_findings.append("current project is not configured in Codex trust table")
global_claude = home / ".claude" / "CLAUDE.md"
global_claude_settings = home / ".claude" / "settings.json"
instructions_mode = project_instructions_mode(global_claude_settings)
agents_fallback_on = instructions_mode in (
"claude-md-or-agents-md",
"claude-md-and-agents-md",
)
nested_agents = nested_agents_files(root)
shared_project_settings = root / ".claude" / "settings.json"
local_project_settings = root / ".claude" / "settings.local.json"
project_rules = root / ".claude" / "rules"
global_rules = home / ".claude" / "rules"
project_skill_roots = [
root / ".claude" / "skills",
root / ".agents" / "skills",
root / ".codex" / "skills",
]
global_skills = home / ".claude" / "skills"
claude_findings: list[str] = []
if yes(claude) == "yes" and claude_delegates:
if claude_aliases_agents:
claude_findings.append("CLAUDE.md resolves to the same physical file as AGENTS.md")
else:
claude_findings.append("CLAUDE.md delegates to AGENTS.md")
claude_reads_agents = yes(agents) == "yes" and agents_fallback_on
if yes(global_claude) == "no" and yes(claude) == "no" and not claude_reads_agents:
claude_findings.append("Claude instruction surface not found")
# A root CLAUDE.md switches the whole project off the AGENTS.md path, so the
# nested guides stop loading with it. The one exception is the both mode,
# where AGENTS.md is read beside CLAUDE.md and the walk still reaches them,
# unless CLAUDE.md IS that AGENTS.md, in which case the deduplicated chain
# is skipped and the nested files go dark again. Measured all four ways.
both_mode = instructions_mode == "claude-md-and-agents-md"
nested_hidden = nested_agents and yes(claude) == "yes" and (
not both_mode or claude_aliases_agents
)
if nested_hidden:
claude_findings.append(
f"a root CLAUDE.md hides {len(nested_agents)} nested AGENTS.md from Claude"
)
if (
yes(global_claude) == "yes"
and has_operational_rules(global_claude)
and yes(global_codex_agents) == "yes"
and looks_identity_only(global_codex_agents)
):
codex_findings.append(
"global Codex AGENTS.md has identity/memory context but lacks operational rules present in global Claude CLAUDE.md"
)
codex_config_text = read(codex_config) if yes(codex_config) == "yes" else ""
if (
'sandbox_mode = "danger-full-access"' in codex_config_text
and 'approval_policy = "never"' in codex_config_text
):
codex_findings.append(
"Codex runs danger-full-access with approval_policy=never; Codex has no command-level deny mechanism, so the only levers are sandbox_mode and approval_policy -- surface once as a user tradeoff, not a per-project fix"
)
permission_status, permission_lines, permission_findings = summarize_claude_permissions(
global_claude_settings,
shared_project_settings,
local_project_settings,
has_task_scoped_env_policy([global_claude, global_codex_agents, agents, claude]),
)
duplicate_status, duplicate_lines = summarize_skill_duplicates(root, home)
path_context_status, path_context_lines = summarize_rule_context(
[("project", project_rules), ("global", global_rules)], root
)
conflict_findings: list[str] = []
if yes(agents) == "yes" and yes(claude) == "yes" and not claude_delegates:
conflict_findings.append("AGENTS.md and CLAUDE.md both exist; verify they do not diverge")
if duplicate_status == "WARN":
conflict_findings.append("active skill routing has broken links, name collisions, or divergent copies")
instruction_status = "FAIL" if not instruction_files else ("WARN" if instruction_findings else "PASS")
codex_status = "WARN" if codex_findings else "PASS"
claude_status = (
"WARN"
if (
(
claude_findings
and any(
marker in " ".join(claude_findings)
for marker in ("surface not found", "hides")
)
)
or permission_status == "WARN"
or path_context_status == "WARN"
)
else "PASS"
)
conflict_status = "WARN" if conflict_findings else "PASS"
print("=== AGENT INSTRUCTION SURFACE ===")
print(f"agent_instruction_status: {instruction_status}")
print(f"mode: {mode}")
print(f"AGENTS.md: {yes(agents)}")
print(f"CLAUDE.md: {yes(claude)}")
print(f"claude_aliases_agents: {'yes' if claude_aliases_agents else 'no'}")
print(f"claude_delegates_to_agents: {'yes' if claude_delegates else 'no'}")
print(f".github/copilot-instructions.md: {yes(root / '.github' / 'copilot-instructions.md')}")
print(f".github/instructions/*.md: {github_instruction_count}")
print(f"GEMINI.md: {yes(root / 'GEMINI.md')}")
print_list("instruction_files", [rel(path, root) for path in instruction_files])
print_list("instruction_findings", instruction_findings)
print("=== CODEX SURFACE ===")
print(f"codex_status: {codex_status}")
print(f"global_agents_md: {yes(global_codex_agents)}")
print(f"global_config_toml: {yes(codex_config)}")
print(f"project_trust: {trust}")
print_list("features", features, limit=20 if mode == "summary" else None)
print_list("enabled_plugins", plugins, limit=20 if mode == "summary" else None)
print_list("marketplaces", marketplaces, limit=20 if mode == "summary" else None)
print_list("redacted_config_entries", redacted)
print_list("codex_findings", codex_findings)
print("=== CLAUDE SURFACE ===")
print(f"claude_status: {claude_status}")
print(f"global_claude_md: {yes(global_claude)}")
print(f"project_instructions_mode: {instructions_mode}")
print(f"nested_agents_md: {len(nested_agents)}")
print(f"global_settings_json: {yes(global_claude_settings)}")
print(f"project_claude_md: {yes(claude)}")
print(f"shared_settings_json: {yes(shared_project_settings)}")
print(f"settings_local_json: {yes(local_project_settings)}")
rule_count = len(unique_physical_files(list(project_rules.glob("*.md"))))
local_skill_count = len(unique_physical_files([
path
for skill_root in project_skill_roots
if resolve_audit_dir(skill_root) is not None
for path in skill_root.glob("*/SKILL.md")
]))
global_skill_count = len(
unique_physical_files(list(global_skills.glob("*/SKILL.md")))
)
print(f"project_rules: {rule_count}")
print(f"project_skills: {local_skill_count}")
source_skill_count = (
len(unique_physical_files(list((root / "skills").glob("*/SKILL.md"))))
if resolve_audit_dir(root / "skills") is not None
else 0
)
print(f"source_skills: {source_skill_count}")
print(f"global_skills: {global_skill_count}")
print_list("claude_findings", claude_findings)
for line in permission_lines:
print(safe_label(line, 2_000))
for line in runtime_inventory(root, home):
print(safe_label(line, 2_000))
for line in path_context_lines:
print(safe_label(line, 2_000))
for line in duplicate_lines:
print(safe_label(line, 2_000))
_, pi_lines = summarize_pi_surface(root, home)
for line in pi_lines:
print(safe_label(line, 2_000))
print("=== INSTRUCTION CONFLICTS ===")
print(f"conflict_status: {conflict_status}")
print_list("conflict_findings", conflict_findings)
return 0
if __name__ == "__main__":
sys.exit(main())