feat: analyze bundled permission grants

[chrisknvidia]

Part of #399

Depends on #404.

Scope

This draft implements the BH3 follow-up for the remaining project-settings surface in issue #399:

• analyze exact project settings roots: .claude/settings.json and .claude/settings.local.json
• structurally classify permission-widening allow, additionalDirectories, and defaultMode declarations
• distinguish blocking critical grants from nonblocking, conditional, ignored, and restrictive settings
• preserve Claude Code trust, provenance, distribution, and interface qualifiers without claiming universal runtime activation
• merge BH1/BH2/BH3 into one terminal inspection result per physical settings document
• cover directory, ZIP, nested ZIP, OOXML, sanitized evidence, scoring, output formats, baselines, and incomplete/fatal behavior

Implementation status

The BH3 slice is implemented through production integration, user-facing documentation, adversarial review, and practical E2E verification.

Completed:

• pure permission model pinned to Claude Code 2.1.241 semantics
• bounded allow/ask/deny/additionalDirectories grammar, conservative precedence, path normalization, and fail-closed outcomes
• parse-once exact settings-root integration with one merged BH1/BH2/BH3 ledger owner
• bounded optional source-location recovery
• typed source-v2 provenance across direct, ZIP, nested ZIP, literal-bang, DOCX, XLSX, and PPTX namespaces
• BH3 registration, provider-local structural routing, suppression-aware scoring, and strict blocking score floor
• terminal, JSON, Markdown, and SARIF output coverage; baselines; exit 0/1/2/PARTIAL behavior; privacy canaries; and resource-limit coverage
• README documentation updated to state trust and runtime boundaries precisely

Verification

• 4,677 passed, 13 skipped, 92 deselected, and 4 expected failures in the broad non-provider regression suite
• independent final audit: 1,077 affected unit/regression tests passed; 54 real graph/CLI/archive integration tests passed; 138,811 matcher-oracle combinations had zero mismatches
• 81 passed in the broader practical integration suite; the sole remaining failure is test_graph_surfaces_degraded_llm_stage, reproduced unchanged on a fresh origin/main checkout
• Ruff, format checks, mypy for changed production modules, package build, DCO, and all hosted CI checks pass
• fresh Docker image verified a retained BH3 result with exit 1, score floor, DO_NOT_INSTALL, successful analysis, and no raw privacy canaries
• live Claude Code 2.1.241 CLI probe verified that a local project allow rule executed a harmless command, while the equivalent untrusted shared project rule was ignored and denied; IDE, Desktop, web/cloud, and SDK interfaces were not live-probed
• pinned public corpus calibration covered 4,529 components and found no exact project settings surface; this confirms the surface is rare in that corpus but cannot measure real-world BH3 false positives

Dependency and review

This branch includes draft PR #404 through head a71fd69. The reviewable BH3 delta is a71fd69..49b0d58 (32 signed-off commits). It targets main and must merge after #404.

This PR remains draft. The existing changes-requested review was submitted against old head 8cf3376, before any BH3 delta existed, and remains for the reviewer to revisit.

[rng1995]

[SkillSpector Review]

This draft is not yet code-reviewable for its stated BH3 permission-grant scope. PR #429 and dependency PR #404 currently point to the identical head commit (8cf3376), so the displayed 18k-line diff is entirely inherited BH1/BH2 work and there are no BH3-specific production or test changes to evaluate.

Before requesting re-review, please:

1. Fast-forward/rebase this branch onto the final reviewed #404 head. #404 currently conflicts with main, so resolve that dependency conflict first and propagate the resolved head here.
2. Add the BH3 implementation and its focused positive, negative, boundary, archive, ledger, scoring, output-format, and baseline regressions described in this PR.
3. Isolate the stacked diff while #404 remains open—preferably by temporarily targeting #404's branch as this PR's base—so reviewers see only BH3 changes rather than re-reviewing the entire dependency.
4. Align the documented Claude Code semantics snapshot: this PR description names 2.1.241, while the inherited README/design currently state 2.1.238.

No inline findings are attached because this head contains no #429-specific code. Please keep the PR in draft and ping for re-review after the BH3 delta is present and the dependency/base conflicts are resolved.

[rng1995]

Reviewed this head against #404. It is the exact same commit (8cf33768) and contains no permission-grant/BH3 implementation to review; the PR description also says production implementation has not started and depends on #404. I left the hook-flow findings on #404 to avoid duplicate inline threads. Please add the #429-specific implementation (and return this to draft until then), then re-request review.

[rng1995]

Requesting changes because this PR is marked ready for review but has no #429-specific implementation: its head is byte-for-byte identical to #404, and the PR description says production implementation has not started. Please return it to draft, add the permission-grant/BH3 delta after its dependency lands, and then re-request review. The hook-flow implementation findings remain on #404 to avoid duplicate threads.

[chrisknvidia]

Implementation checkpoint: the BH3 delta is now present and pushed through 6dce677. The reviewable stacked range is 5f66e0e..6dce677; #404 remains the dependency. All hosted checks are green, the broad non-provider suite passed, issue-specific and archive/output E2E passed, and practical Docker plus one live Claude Code 2.1.241 trust probe were completed. The one practical integration failure was reproduced unchanged on fresh origin/main and is unrelated to this branch.

The existing changes-requested review targets old commit 8cf3376, when this branch had no BH3 changes. I am leaving that review untouched for the reviewer and keeping this PR in draft as requested.

[mohgupta-ship-it]

Powered by Codex: PR council review result.

This is a triage signal, not a maintainer approval.

• Rating: new feature
• Confidence: medium-low
• Status read: Draft, changes requested, merge blocked
• Review method: fresh GitHub metadata/body/files/reviews/checks plus selected diffs; council lenses were spec fit, dead-code/reachability, YAGNI/scope, design/coupling, and code standards/tests.
• Council assessment: Permission-grant/BH3 surface depends on feat: analyze bundled hook execution surfaces #404 and inherits unresolved hook-flow risk. Large new BH3 logic should not be promoted independently.
• Recommended action: Do not promote as ready; de-risk feat: analyze bundled hook execution surfaces #404 first, then request fresh review on BH3-specific changes.