Skip to content

feat(hooks): stage consent-aware Claude standalone inline hooks - #3332

Draft
Daniel Meppiel (danielmeppiel) wants to merge 1 commit into
mainfrom
danielmeppiel-inline-hook-consent
Draft

Daniel Meppiel (danielmeppiel) wants to merge 1 commit into
mainfrom
danielmeppiel-inline-hook-consent

Conversation

@danielmeppiel

Copy link
Copy Markdown
Collaborator

fix(hooks): stage consent-aware Claude standalone inline hooks

Description

TL;DR

This held draft adds APM-side consent, whole-primitive withholding, resource relocation and read-only replay for selected Claude commands, skills and non-plugin agents with structured inline hooks. It reuses package/type consent rather than creating a new grant store or promoting scoped hooks into global settings. Installed-CLI witnesses pass, but this does not complete #3227 or certify any native Claude version.

Warning

Not ready to merge. Native command/skill/agent x project/user certification is absent, native trust/probe permission remains withheld, public sibling composition and additional acceptance work remain below. No native client or hook was invoked.

Problem (WHY)

  • Three real installed-CLI before witnesses deployed denied hook-bearing primitives: command conversion dropped the hooks, while skills and agents bypassed their consent.
  • Audit replay initially reported deliberate withholding as missing output. User-scope resource paths also disagreed with scratch replay.
  • Approval discovery initially offered hooks from an unselected skill or excluded target. Both failures are now regression cases.

These are observed failures, not inferred native-runtime claims. The accepted scope explicitly says "withhold the whole affected hook-bearing primitive rather than silently remove protective hooks". The evidence follows Agent Skills' "Refine with real execution": retain failures as well as successful reruns.

Approach (WHAT)

  1. Read structured declarations only from the existing selected primitive anchors.
  2. Apply existing package/type hooks permission and a Claude-specific whole-primitive view.
  3. Reuse hook selection, path rewriting and bundle copying; keep inline descriptors out of global rendering.
  4. Replay current effective consent and preserve edited or unverified output during revocation.

This keeps the fragile admission sequence explicit rather than adding a second authority: "Be prescriptive".

Implementation (HOW)

Files Change and boundary
src/apm_cli/install/deployable_source_plan.py, deployment_plan.py Selected inline declarations, target-specific withheld paths and shared preparation. No second candidate traversal.
src/apm_cli/integration/inline_hooks.py Scoped declaration/Markdown adapter and resource materialization. Its temporary native validation must compose with #3226's public placement-aware owner before landing.
src/apm_cli/integration/hook_source_selection.py, hook_integrator.py, hook_bundle.py Optional inline selection, inline_for(target), strict required-resource checks and edited-resource protection. Default global-hook behavior remains separate.
src/apm_cli/install/exec_gate.py, template.py, src/apm_cli/security/executables.py Existing consent consumes selected declarations; first-party trust is explicit, not inferred from _local; user scope reads its real manifest.
src/apm_cli/commands/approve.py Locked package, canonical target selection and skill subset govern inline approval inventory.
src/apm_cli/install/services.py, src/apm_cli/integration/command_integrator.py, agent_integrator.py, skill_integrator.py, skill_preflight.py Native scoped output, required resources before primitive activation, per-target withholding and unrelated-text preservation.
src/apm_cli/install/context.py, phases/cleanup.py, src/apm_cli/integration/cleanup.py Require a recorded hash for withheld-output removal; preserve edits and expose incomplete revocation.
src/apm_cli/install/drift.py, src/apm_cli/policy/ci_checks.py, src/apm_cli/commands/audit.py Current consent/policy replay and user live-root path rendering while writes remain scratch-bound.
.apm/architecture/owners/install-deployment.json, scripts/architecture_linter/checks/install_inline_hooks.py, install_deployment_analyzers.py, tests/integration/test_architecture_owner_rule_mutations.py One new scoped adapter owner and a mutation that bypasses per-target withholding; existing source-plan owner retained.
tests/integration/test_inline_hook_consent_lifecycle.py, tests/unit/integration/test_inline_hooks.py, tests/integration/test_executables_gate_integration.py Harmless installed-CLI lifecycle and source boundaries; explicit first-party test input.
docs/src/content/docs/producer/author-primitives/{hooks-and-commands,skills}.md, docs/src/content/docs/reference/cli/{approve,audit}.md Scope, resources, consent, audit and native restart/trust caveats.
packages/apm-guide/.apm/skills/apm-usage/{commands,governance,package-authoring}.md Matching packaged guidance. README, changelog, native clients and release metadata untouched.

Source anchors: selected-source owner and native-only selector.

Diagrams

Dashed nodes show the inline-specific path; deployment and scratch replay consume the same selected sources and effective consent.

flowchart LR
    subgraph Selection[Selection]
        A[DeployableSourcePlan.create]
        B[read_inline_hook_document]
        A --> B
    end
    subgraph Consent[Existing package consent]
        C{check_executable_approval}
        B --> C
    end
    subgraph Projection[Claude projection]
        D["for_target: withhold whole primitive"]
        E[select_hook_sources and bundle copier]
        F["Command, Skill and Agent integrators"]
        C -->|Pending or denied| D
        C -->|Allowed or gate disabled| E
        E --> F
    end
    subgraph Audit[Read-only replay]
        G["run_replay: selected sources and current consent"]
        H[diff_scratch_against_project]
        G --> H
    end
    D --> H
    F --> H
    classDef new stroke-dasharray: 5 5;
    class B,D,E,F,G new;
Loading

Trade-offs

  • Whole withholding, not weakened text. Declining the hook also makes its enclosing Claude primitive unavailable; separate pure text remains.
  • Bounded paths, not shell interpretation. Supported literal resources use existing bundle owners; this is not universal Markdown execution control.
  • Public composition, not private copying. [FEATURE] Exclude dev-only files (e.g. evals/) from skill bundles at install time #3215 author subtraction/provenance and Hook files cannot be limited to a target: Copilot events leak into Claude settings #3226 native placement validation must be composed from their actual public carriers. This draft exposes the shared resource seam without claiming that integration is complete.
  • No native equivalence claim. Installed-CLI tests verify APM output, not native registration/lifetime. Running-session hooks may survive file removal.
  • No spec waiver or full-suite claim. Normative clarification, conformance evidence, remaining scenarios and full ordinary regression qualification are unfinished.

Benefits

  1. Denied command, skill and agent cases no longer activate an unapproved or weakened Claude primitive.
  2. Six project/user approval-revocation scenarios distinguish withheld state from missing approved output.
  3. Unselected skills/targets do not acquire inline grants; edited scripts and Node sidecars survive refused reinstall.

Issue and approved scope

Issue: Related to #3227.

Human scope-approval comment: #3227 (comment); explanatory record: #3227 (comment). Separate current-session execution delegation authorized implementation. The trusted helper returned record-present, authorizes_implementation:false; that evidence was not treated as permission.

This PR does not complete the issue. Preserve Roger Siegenthaler (@siegenthalerroger)'s original investigation attribution; no implementation claim or assignment is attributed to them.

Remaining acceptance gates:

  • Compose public [FEATURE] Exclude dev-only files (e.g. evals/) from skill bundles at install time #3215 descriptor provenance, author-subtracted declaration inventory and retained-source validation ordering, including surviving inline projection.
  • Compose public Hook files cannot be limited to a target: Copilot events leak into Claude settings #3226 placement=settings|skill|agent validation; commands use skill placement, agents do not accept skill-only once. Remove temporary validation vocabulary.
  • Complete real interactive APM, direct/transitive, update, missing-hash/foreign ownership, paired JSON/opaque-plugin and current-policy/cold-replay acceptance cases.
  • Complete specification/conformance work and normal advisory review for changed promises.
  • Qualify the final composed snapshot with the remaining ordinary regression suite; earlier failures and any unexecuted cases remain visible.
  • Obtain separately authorized, version-qualified native command/skill/agent x project/user evidence. Plugin evidence is not a substitute.

Type of change

  • Bug fix
  • New feature
  • Documentation
  • Maintenance / refactor

Testing

  • Tested locally
  • All existing tests pass
  • Added tests for new functionality (if applicable)

Validation

Exact head: 5e30371ba77305382201645a6c14b90f51593891, based on actual public main 3b9a8503e0bf5978253f769f823bb84340edfc4a. Local checks below are not a claim of green GitHub CI, full-suite completion or native certification.

Exact commands and observed results

Every test/quality command below ran inside the campaign admission wrapper:
python3 /Users/danielmeppiel/.copilot/session-state/f79e464c-180e-4be3-9056-0773aa679a1a/files/campaign-em/run-heavy.py --lane 3227 --timeout 1800 -- env PATH="$PWD/.venv/bin:$PATH" APM_BINARY_PATH="$PWD/.venv/bin/apm" bash /Users/danielmeppiel/.copilot/session-state/d9a7aa47-b6e4-4956-9ba9-4467b9d2a9fe/files/qualify-inline.sh — exit 0. Owned Python 3.12.10, CLI shebang and editable import belong to this checkout.

Command within that script Result
uv run --frozen --extra dev ruff check src/ tests/ scripts/lint_architecture_boundaries.py scripts/architecture_linter/ scripts/windows_native_symlink_probe_entry.py All checks passed!
uv run --frozen --extra dev ruff format --check src/ tests/ scripts/lint_architecture_boundaries.py scripts/architecture_linter/ scripts/windows_native_symlink_probe_entry.py 2088 files already formatted
uv run --frozen --extra dev python -m pylint --disable=all --enable=R0801 --min-similarity-lines=10 --fail-on=R0801 src/apm_cli/ scripts/lint_architecture_boundaries.py scripts/architecture_linter/ scripts/windows_native_symlink_probe_entry.py Your code has been rated at 10.00/10 (previous run: 10.00/10, +0.00)
bash scripts/lint-auth-signals.sh [+] auth-signal lint clean
CI-equivalent YAML/path regex and 2100-line guards in the script YAML, portable-path and 2100-line CI mirrors passed
bash scripts/lint-architecture-boundaries.sh Exit 0, no output
.venv/bin/python -m pytest -q tests/integration/test_inline_hook_consent_lifecycle.py tests/unit/integration/test_inline_hooks.py tests/integration/test_executables_gate_integration.py tests/unit/install/test_security_scan_scope.py 'tests/integration/test_architecture_owner_rule_mutations.py::test_owner_rule_catches_its_guard_mutation[install-deployment-inline-hooks]' tests/integration/test_architecture_owner_rule_mutations.py::test_owner_rules_report_nothing_before_mutation tests/integration/test_architecture_owner_rule_mutations.py::test_matrix_covers_every_registry_guard_exactly_once --basetemp=/Users/danielmeppiel/.copilot/session-state/d9a7aa47-b6e4-4956-9ba9-4467b9d2a9fe/files/pytest-inline-publish --tb=short 156 passed in 117.69s (0:01:57)
node --test docs/scripts/check-links.test.mjs 14 passed, 0 failed, 0 skipped; checker tests only, not a site build
git diff --exit-code Exit 0; clean snapshot

Final owner-named diagram separately passed:
python3 /Users/danielmeppiel/.copilot/session-state/f79e464c-180e-4be3-9056-0773aa679a1a/files/campaign-em/run-heavy.py --lane 3227 --timeout 1800 -- mmdc -i /Users/danielmeppiel/.copilot/session-state/d9a7aa47-b6e4-4956-9ba9-4467b9d2a9fe/files/inline-hook-flow.mmd -o /Users/danielmeppiel/.copilot/session-state/d9a7aa47-b6e4-4956-9ba9-4467b9d2a9fe/files/inline-hook-flow.svg --quiet — exit 0.

Failure history retained: initial three forbidden-deployment witnesses; two withholding-audit failures; one user-path replay failure; earlier 609 passed, 89 failed architecture run (duplicate owner registration, misplaced target-specific routing and upstream ambiguous mutation); targeted 13 passed, 3 failed (first-party fixture layout plus two genuine approval-inventory failures). A prepublication guard also caught 2101 lines in HookIntegrator; its existing docstring was shortened. These were corrected/composed and the bounded exact-head run above passed. This does not assert that the original full mutation run or the full ordinary suite was rerun green.

Scenario Evidence

Paths below are in tests/integration/test_inline_hook_consent_lifecycle.py unless otherwise stated.

# Scenario (user promise) Principle(s) Test(s) proving it Type
1 Denying hooks withholds the whole protected primitive, not unrelated text Governed by policy test_denied_inline_hook_withholds_whole_primitive (regression-trap for #3227) e2e
2 Approval preserves native data and required bytes through reinstall in both scopes Secure by default, DevX test_approved_inline_hook_preserves_native_definition e2e
3 Approve/revoke and read-only audit agree in all six variants Governed by policy test_inline_hook_approval_revocation_and_readonly_audit e2e
4 Malformed or unrepresentable selected hooks fail before activation Secure by default test_invalid_inline_definition_fails_before_activation e2e
5 Claude withholding does not alter paired Copilot output Multi-harness support test_inline_withholding_does_not_change_other_target e2e
6 Personal primitive/resource edits survive a refused operation Secure by default test_edited_inline_primitive_is_not_silently_revoked, test_inline_resource_edits_block_reinstallation_without_overwrite e2e
7 Genuine first-party content remains trusted; unselected content gains no grant Governed by policy test_first_party_inline_hooks_do_not_need_dependency_approval, test_approval_inventory_uses_actual_selected_inline_sources e2e
8 Inline fields do not become global descriptors or activate ignored plugin-agent fields Secure by default tests/unit/integration/test_inline_hooks.py integration

How to test

  • Run the bounded command above through the approved campaign wrapper; expect 156 passes and no native invocation.
  • Inspect the approval/revocation fixtures for all three primitives and both scopes; the whole protected primitive disappears while separate text remains.
  • Inspect resource and edited-output cases; a failed reconciliation preserves personal bytes.
  • Complete the unchecked acceptance gates before requesting final qualification; do not accept native trust or run native hooks without separate authorization.

Spec conformance (OpenAPM v0.1)

If this PR changes behaviour that an OpenAPM v0.1 req-XXX covers,
confirm the three-step ritual in the
development guide:

  • Spec edit: docs/src/content/docs/specs/openapm-v0.1.md updated
    (new/changed <a id="req-XXX"></a> anchor + prose + Appendix C
    row).
  • Manifest edit: docs/src/content/docs/specs/manifests/openapm-v0.1.requirements.yml
    updated.
  • Test edit: a @pytest.mark.req("req-XXX") test under
    tests/spec_conformance/ added or extended.
  • CONFORMANCE.{md,json} regenerated via
    uv run --extra dev python -m tests.spec_conformance.gen_statement
    and committed.
  • N/A -- this PR does not change OpenAPM-observable behaviour.

Pending, not N/A. Existing executable admission, deny precedence and selected-source promises (req-sc-009, req-sc-011, req-sc-015) are affected. Whole-primitive semantics and scoped native support require the normal specification/conformance treatment before this held draft can land. No spec waiver is claimed.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

Route selected standalone hooks through package consent and shared resource owners. Withhold whole denied primitives and replay current consent without mutating the workspace. Native certification, public sibling composition and remaining acceptance evidence remain explicit draft gates for #3227.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: d9a7aa47-b6e4-4956-9ba9-4467b9d2a9fe
@danielmeppiel

Copy link
Copy Markdown
Collaborator Author

Status: parked as a draft (maintainer decision, 2026-11-12). This builds on the same Claude native groundwork as #3290, which is being revived first. Once #3290 lands, this will be rebased onto it and completed against #3227's accepted scope, including the native Claude check for commands, skills and agents at project and user scope.


Posted with AI assistance on behalf of Daniel Meppiel (@danielmeppiel).

This branch has not been deployed

No deployments
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.

1 participant