Skip to content

fix(trust): check and the Claude Code hook protect a declared policy pack (#1128) - #1130

Merged
pengfei-threemoonslab merged 3 commits into
mainfrom
claude/check-hook-declared-policy-packs
Nov 11, 2026
Merged

pengfei-threemoonslab merged 3 commits into
mainfrom
claude/check-hook-declared-policy-packs

Conversation

@pengfei-threemoonslab

@pengfei-threemoonslab pengfei-threemoonslab commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Closes #1128. Follow-up to #1075 / #1127, which is now on main (b581c39). It makes PR-time verify treat every declared pack as a trust root. This PR closes the local half: a coding agent is stopped before the pull request, not only at it.

  • check routes an edit to a declared policy pack to review, as it routes policies/**. On fix(trust): treat manifest-declared policy packs as trust roots (#1075) #1127's head, a branch that edited only the vendor/shipgate-policies/org-release.yaml its manifest declares got decision: allow from ./shipgate check --base main --head HEAD --format agent-boundary-json. The same edit to policies/org.yaml got require_review. Now both get BOUNDARY-PROTECTED-SURFACE-UNCLASSIFIED (require_review, medium) and control.state: review_publishable. The vendored row also records trust_root_class: policy, so the gate-governing band check keeps it off the graded agent route. That is the treatment a custom-named manifest (manifest) and a custom --policy file (policy) already get. The base's declarations come from the configured manifest as committed at the base ref, so dropping a declaration and editing the pack in one change still needs a human. A provided --diff, and the shipgate.check MCP tool, read only the working tree's manifest and run no Git.
  • One resolver. core.trust_roots.manifest_policy_pack_paths is fix(trust): treat manifest-declared policy packs as trust roots (#1075) #1127's resolution moved into core/. It is lexical, resolves against the manifest's directory, keeps only in-repository paths, and returns them in declaration order. verify's _configured_input_trust_roots now calls it, with the same results and the same setdefault order per manifest. check and verify's boundary assessment call it too. A changed path is matched by is_manifest_policy_pack, the rule configured_input_trust_root uses: normalized and ASCII-case-insensitive. So check and verify cannot pick a different changed file.
  • verify publishes the boundary row that check publishes. assessment_for_scan_context receives the same packs through a run-private VerificationContext.manifest_policy_packs, which is exclude=True and never serialized. A vendored-pack edit now gets SHIP-AGENT-BOUNDARY-PROTECTED-SURFACE-UNCLASSIFIED (host_boundary) beside fix(trust): treat manifest-declared policy packs as trust roots (#1075) #1127's SHIP-VERIFY-TRUST-ROOT-TOUCHED, exactly as a policies/ edit already did. Without this, check and verify would publish different boundary evidence for one diff. The assessment_for_scan_context comment names that as the defect it exists to prevent.
  • The Claude Code hook asks before an edit to a declared pack. The rendered PROTECTED_SURFACES cannot know manifest paths, so a _ConfiguredSurfaces lookup sits beside it. It is used at every site that used _protected_surface_for(path, configured_manifest=args.config): PreToolUse, the approval memory, the PostToolUse nudge, and both Stop branches. It reads the configured manifest from the working tree, and with one git cat-file as --base holds it. That covers a pack whose declaration the change removed.
    • It parses a manifest only when the manifest can name a pack, that is, when it contains policy_packs or a backslash. In YAML and JSON a key is literal text unless an escape spells it.
    • Parsing goes through the existing agents-shipgate org policy-packs --json, on a private copy of the bytes, so no YAML parser is duplicated in the hook. The answer is kept per manifest version, by digest, in the existing hook state file under declared_policy_packs.
    • If the CLI cannot read a manifest that names policy_packs, every file whose name the manifest spells is protected. A CLI that did not start is asked again on the next event.
    • The hook's lexical resolution mirrors core's and is held to it by a shared-table test, the pattern _glob_match already uses.
  • _read_untracked_file gains a limit keyword (the 4 MiB the CLI reads a manifest with) and now loops over short reads. Existing callers keep the 128 KiB default.
  • CHANGELOG: a ## Unreleased bullet under ### Changes, beside fix(release): finalize waits out PyPI index lag instead of failing seconds after the upload #1132's ### Packaging entry. STABILITY gets the migration note check-hook-declared-policy-packs-1128, above the notes stamped 1.3.0. docs/checks.md (and llms-full.txt, rebuilt), docs/organization.md, docs/agents/use-with-claude-code.md, and the _run/_run_git_bounded rows of docs/trust-model.md § Process Boundaries are updated. No new spawn site: the hook calls the CLI and Git through its existing _run and _run_git_bounded.

Surface discipline: no new surface. No CLI flag, command, schema, contract, rule or check ID, severity, action or trust_root_class value is added. The hook reads the existing org policy-packs JSON (org_governance_schema_version: "0.1"). Neither check nor the hook has its own row in docs/distribution-surfaces.md. The mcp_server row's "no tool runs git" claim still holds, because a provided diff never reads a base. So the registry and tests/test_distribution_surface_parity.py are unchanged. Headline metric: blocked-recall, moved earlier. A vendored-pack edit is stopped in the agent's session and in check, not only at the pull request.

Type

  • Check or risk-model change
  • Input adapter change
  • CLI or GitHub Action behavior
  • Report, schema, or SARIF output
  • Documentation only

Authorship

  • A coding agent wrote some or all of this change. Agent: Claude Code (claude-opus-5-5)
  • A person read the whole diff before opening this pull request.

No person has read this diff yet. It needs the owner's review before merge.

Verification

CI is authoritative for python -m ruff check ., python -m compileall -q src tests, and python -m pytest.

Additional local checks run (Python 3.12, macOS):

  • Reproduction on main b581c39 (fix(trust): treat manifest-declared policy packs as trust roots (#1075) #1127; the same tree as its head fc1d34b). A scratch repository whose shipgate.yaml declares vendor/shipgate-policies/org-release.yaml, with a pr branch that edits only that file. check --base main --head HEAD: allow before, require_review / review_publishable after, with evidence: {kind: protected_surface_unclassified, trust_root_class: policy}. Also checked after the change: an un-declare-and-edit range (rows for both shipgate.yaml and the pack), --base HEAD, a flagless run, --diff, and an untracked optional pack that the manifest declares and the base lacks. All routed to review. The policies/org.yaml result is identical before and after (sorted-key JSON comparison). In verify, the policies/ fingerprints (fp_fda129e8a7c4d352, fp_e48e0cb023cc0e6c) and the vendored trust-root finding (fp_21dc307cfaff8f99) do not move.
  • Hook, rendered and run with python3 against the real CLI. It asks for the declared pack. It still asks after the working-tree manifest drops the declaration, with --base main, and not with an unavailable base. It asks for a file a broken manifest names, and not for an unrelated file. It does not re-ask in the same session once the edit was allowed. The first event costs about 1.7 s, almost all of it one org policy-packs run. Later events are about 0.15 to 0.2 s. An ordinary edit in a repository without policy_packs went from about 0.10 s to about 0.15 s (one git cat-file).
  • tests/test_declared_policy_pack_boundary.py: 22 cases. Run on an export of fc1d34b (fix(trust): treat manifest-declared policy packs as trust roots (#1075) #1127's tree) with the same file, 20 fail. The 2 that pass are invariants: an undeclared file stays allow, and a policies/org.yaml row is the same with or without a declaration.
  • Focused suites, -n 8 (hooks, boundary, test_verify_pr_controlled_inputs.py, first adoption, plugin-hook routing): pass, except one test_instruction_structure_hooks.py[acceptEdits] case. Its 6 s preflight preview timed out under load. That path is unchanged here (a static hit, before any declared-pack lookup), and the file passes on its own.
  • Full suite, -n auto -m "not perf and not slow" --ignore=tests/test_adapter_static_only.py, with an empty XDG_CONFIG_HOME (22,367 tests): 4 failures, all environmental. Three are test_schema_roundtrip.py and one is test_published_schema_freeze.py's version-bump test. The local venv has pydantic 2.13.4 while constraints/dev.txt pins 2.14.3, and all four fail identically on the unpatched fc1d34b export. CI's locked closure is authoritative for them. tests/test_latency_budget.py -m perf: pass.
  • tests/test_adapter_static_only.py: pass (no new spawn site; § Process Boundaries keys unchanged). ruff check .: pass. compileall -q src tests: ok. scripts/regenerate_goldens.py --check: Checked 24 sample artifacts; 0 changed.
  • tests/shard_seconds.json: the new file was measured serially (44.3 s, 22 cases) and recorded as a supplemental increment, as fix(trust): treat manifest-declared policy packs as trust roots (#1075) #1127 did.

Release-readiness notes

  • No user-code import added to default scan paths
  • No network access added to default scan paths
  • New or changed check IDs are documented in docs/checks.md (none added or changed; the protected-surface section now names declared packs)
  • Report/schema changes are additive or documented in STABILITY.md

v1.3.0 was tagged at its release-prep commit (f96f1e9), so this change ships in the next release, where its entry already is: under ## Unreleased.

Decisions taken

  • Base ref, not merge base, for check's base declarations. verify reads its base manifest at --base (_base_manifest), so check reads it at the base ref it resolved: the named --base, the detected default base, or HEAD for --base HEAD. A committed range's base and a worktree run's merge base usually hold the same manifest.
  • verify's boundary assessment gets only the manifest-declared packs. It does not get verify: read an in-repo --diff-from and ci.mode from the base, never from the PR head #1024's command-line inputs. check has no --policy-pack, --baseline or --diff-from, so routing those would add verify-only rows that no check run can match. verify: read an in-repo --diff-from and ci.mode from the base, never from the PR head #1024's trust-root findings for them are unchanged.
  • The hook asks the CLI instead of parsing YAML. The hook is stdlib-only, and docs/distribution-surfaces.md says a surface that can read the answer from the package should not carry a second implementation. org policy-packs --json already lists the declared paths. The digest cache keeps the cost to one CLI run per manifest version. The backslash-or-policy_packs pre-filter keeps repositories without packs off the CLI entirely.
  • Degraded mode protects names, not everything. If a manifest names policy_packs but cannot be read, asking on every edit would train people to click through, and asking on none would fail open. So the hook asks for the files that manifest spells by name.

Protected paths touched

none

Follow-up candidates (not in this PR)

  • preflight classifies with the trust-root table only. --changed-files naming a vendored pack returns no touch and agent_action_required, while policies/org.yaml gets a policy touch and human_review_required. core/trust_roots.py's docstring lists the preflight router among the consumers that must classify identically. Preflight has no base ref, so only the head manifest could contribute without a new flag.
  • scan --changed-files (_build_verification_context) still carries no configured inputs, as fix(trust): treat manifest-declared policy packs as trust roots (#1075) #1127 noted. Folding it in means loading the manifest at the CLI layer before run_scan, against a root that _configured_manifest_identity does not return.

🤖 Generated with Claude Code

…pack (#1128)

After #1075 only PR-time verify knew the packs a manifest declares.
`check --base main --head HEAD` answered `allow` for a change that edited
only `vendor/shipgate-policies/org-release.yaml`, while the same edit to
`policies/org.yaml` got `require_review`. The installed PreToolUse hook let
the edit land without asking. And verify's boundary assessment published
SHIP-AGENT-BOUNDARY-PROTECTED-SURFACE-UNCLASSIFIED for the policies/ file but
not for the vendored one.

- core/trust_roots: manifest_policy_pack_paths, #1127's lexical resolution
  moved to core, and is_manifest_policy_pack, the normalized casefold match
  configured_input_trust_root uses. verify's _configured_input_trust_roots
  calls the resolver; its output is unchanged.
- check: the base manifest as committed at the base ref, plus the head
  manifest, declare the packs. A provided diff, and the MCP tool, read the
  working tree only and run no Git. evaluate_agent_boundary routes each pack
  as policies/** is routed. It records trust_root_class: policy only where
  the trust-root table does not classify the path, so it never takes the
  graded agent route, and no structural shortcut clears it.
- verify: the same packs reach assessment_for_scan_context through a
  run-private VerificationContext field, so verify publishes the boundary
  row that check publishes.
- hook: _ConfiguredSurfaces replaces the static lookup in PreToolUse, the
  approval memory, the PostToolUse nudge and the Stop hook. It reads the
  manifest in the working tree and at --base. It parses a manifest only when
  the text can name a pack, through `agents-shipgate org policy-packs --json`
  on a private copy, once per version (kept in the hook state).

policies/** rows and fingerprints are byte-identical. No schema, contract,
rule ID, check ID, severity or trust_root_class value moves.
main promoted `## Unreleased` to `## 1.3.0 - 2026-11-08` and stamped the
migration notes 1.3.0 (#1129). #1128 is not in the prepared 1.3.0 notes,
so its CHANGELOG entry moves to a new `## Unreleased` section, and its
STABILITY migration note, still `Unreleased`, moves above the 1.3.0
notes. Both texts are unchanged; everything else is main's.
main re-opened `## Unreleased` with #1132's `### Packaging` entry after
v1.3.0 was tagged. The section now holds both: #1128's `### Changes`
bullet first, as the subsections were ordered before, then #1132's.
Both texts are unchanged; everything else is main's.
@pengfei-threemoonslab
pengfei-threemoonslab merged commit 2227667 into main Nov 11, 2026
16 checks passed
pengfei-threemoonslab added a commit that referenced this pull request Nov 11, 2026
Brings in #1130 (check and the Claude Code hook protect a declared policy pack). The only conflict was CHANGELOG.md's Unreleased Changes list, where both sides added a bullet; both are kept, #1130's first. STABILITY.md and llms-full.txt merged cleanly; llms-full.txt equals a fresh build.
pengfei-threemoonslab added a commit that referenced this pull request Nov 11, 2026
Conflicts: CHANGELOG.md keeps both Unreleased entries (Host comparison,
then #1130's Changes); tests/shard_seconds.json keeps both files' weights
and both supplemental measurements.
pengfei-threemoonslab added a commit that referenced this pull request Nov 11, 2026
Conflicts: CHANGELOG.md keeps both Unreleased entries (Host comparison,
then #1130's Changes); STABILITY.md keeps both migration notes, #1036's
above #1128's. llms-full.txt auto-merged and matches a rebuild.
pengfei-threemoonslab added a commit that referenced this pull request Nov 11, 2026
Conflicts: CHANGELOG.md keeps both Unreleased entries (Host comparison,
then #1130's Changes); STABILITY.md keeps both migration notes, #1011's
above #1128's. install_hooks.py auto-merged; its diff against main is the
branch's own change, unaltered.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

check and the Claude Code hook miss a manifest-declared policy pack outside policies/**

1 participant