Repository navigation
fix(trust): check and the Claude Code hook protect a declared policy pack (#1128) - #1130
Merged
pengfei-threemoonslab merged 3 commits intoNov 11, 2026
Merged
Conversation
…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.
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #1128. Follow-up to #1075 / #1127, which is now on
main(b581c39). It makes PR-timeverifytreat 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.checkroutes an edit to a declared policy pack to review, as it routespolicies/**. On fix(trust): treat manifest-declared policy packs as trust roots (#1075) #1127's head, a branch that edited only thevendor/shipgate-policies/org-release.yamlits manifest declares gotdecision: allowfrom./shipgate check --base main --head HEAD --format agent-boundary-json. The same edit topolicies/org.yamlgotrequire_review. Now both getBOUNDARY-PROTECTED-SURFACE-UNCLASSIFIED(require_review,medium) andcontrol.state: review_publishable. The vendored row also recordstrust_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--policyfile (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 theshipgate.checkMCP tool, read only the working tree's manifest and run no Git.core.trust_roots.manifest_policy_pack_pathsis fix(trust): treat manifest-declared policy packs as trust roots (#1075) #1127's resolution moved intocore/. 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_rootsnow calls it, with the same results and the samesetdefaultorder per manifest.checkandverify's boundary assessment call it too. A changed path is matched byis_manifest_policy_pack, the ruleconfigured_input_trust_rootuses: normalized and ASCII-case-insensitive. Socheckandverifycannot pick a different changed file.verifypublishes the boundary row thatcheckpublishes.assessment_for_scan_contextreceives the same packs through a run-privateVerificationContext.manifest_policy_packs, which isexclude=Trueand never serialized. A vendored-pack edit now getsSHIP-AGENT-BOUNDARY-PROTECTED-SURFACE-UNCLASSIFIED(host_boundary) beside fix(trust): treat manifest-declared policy packs as trust roots (#1075) #1127'sSHIP-VERIFY-TRUST-ROOT-TOUCHED, exactly as apolicies/edit already did. Without this,checkandverifywould publish different boundary evidence for one diff. Theassessment_for_scan_contextcomment names that as the defect it exists to prevent.PROTECTED_SURFACEScannot know manifest paths, so a_ConfiguredSurfaceslookup 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 onegit cat-fileas--baseholds it. That covers a pack whose declaration the change removed.policy_packsor a backslash. In YAML and JSON a key is literal text unless an escape spells it.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 underdeclared_policy_packs.policy_packs, every file whose name the manifest spells is protected. A CLI that did not start is asked again on the next event._glob_matchalready uses._read_untracked_filegains alimitkeyword (the 4 MiB the CLI reads a manifest with) and now loops over short reads. Existing callers keep the 128 KiB default.## Unreleasedbullet under### Changes, beside fix(release): finalize waits out PyPI index lag instead of failing seconds after the upload #1132's### Packagingentry. STABILITY gets the migration notecheck-hook-declared-policy-packs-1128, above the notes stamped 1.3.0.docs/checks.md(andllms-full.txt, rebuilt),docs/organization.md,docs/agents/use-with-claude-code.md, and the_run/_run_git_boundedrows ofdocs/trust-model.md§ Process Boundaries are updated. No new spawn site: the hook calls the CLI and Git through its existing_runand_run_git_bounded.Surface discipline: no new surface. No CLI flag, command, schema, contract, rule or check ID, severity, action or
trust_root_classvalue is added. The hook reads the existingorg policy-packsJSON (org_governance_schema_version: "0.1"). Neitherchecknor the hook has its own row indocs/distribution-surfaces.md. Themcp_serverrow's "no tool runs git" claim still holds, because a provided diff never reads a base. So the registry andtests/test_distribution_surface_parity.pyare unchanged. Headline metric: blocked-recall, moved earlier. A vendored-pack edit is stopped in the agent's session and incheck, not only at the pull request.Type
Authorship
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, andpython -m pytest.Additional local checks run (Python 3.12, macOS):
mainb581c39 (fix(trust): treat manifest-declared policy packs as trust roots (#1075) #1127; the same tree as its head fc1d34b). A scratch repository whoseshipgate.yamldeclaresvendor/shipgate-policies/org-release.yaml, with aprbranch that edits only that file.check --base main --head HEAD:allowbefore,require_review/review_publishableafter, withevidence: {kind: protected_surface_unclassified, trust_root_class: policy}. Also checked after the change: an un-declare-and-edit range (rows for bothshipgate.yamland 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. Thepolicies/org.yamlresult is identical before and after (sorted-key JSON comparison). Inverify, thepolicies/fingerprints (fp_fda129e8a7c4d352,fp_e48e0cb023cc0e6c) and the vendored trust-root finding (fp_21dc307cfaff8f99) do not move.python3against 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 oneorg policy-packsrun. Later events are about 0.15 to 0.2 s. An ordinary edit in a repository withoutpolicy_packswent from about 0.10 s to about 0.15 s (onegit 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 staysallow, and apolicies/org.yamlrow is the same with or without a declaration.-n 8(hooks, boundary,test_verify_pr_controlled_inputs.py, first adoption, plugin-hook routing): pass, except onetest_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.-n auto -m "not perf and not slow" --ignore=tests/test_adapter_static_only.py, with an emptyXDG_CONFIG_HOME(22,367 tests): 4 failures, all environmental. Three aretest_schema_roundtrip.pyand one istest_published_schema_freeze.py's version-bump test. The local venv has pydantic 2.13.4 whileconstraints/dev.txtpins 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
docs/checks.md(none added or changed; the protected-surface section now names declared packs)STABILITY.mdv1.3.0was tagged at its release-prep commit (f96f1e9), so this change ships in the next release, where its entry already is: under## Unreleased.Decisions taken
check's base declarations.verifyreads its base manifest at--base(_base_manifest), socheckreads it at the base ref it resolved: the named--base, the detected default base, orHEADfor--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.checkhas no--policy-pack,--baselineor--diff-from, so routing those would addverify-only rows that nocheckrun 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.docs/distribution-surfaces.mdsays a surface that can read the answer from the package should not carry a second implementation.org policy-packs --jsonalready lists the declared paths. The digest cache keeps the cost to one CLI run per manifest version. The backslash-or-policy_packspre-filter keeps repositories without packs off the CLI entirely.policy_packsbut 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)
preflightclassifies with the trust-root table only.--changed-filesnaming a vendored pack returns no touch andagent_action_required, whilepolicies/org.yamlgets apolicytouch andhuman_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 beforerun_scan, against a root that_configured_manifest_identitydoes not return.🤖 Generated with Claude Code