feat: analyze bundled hook execution surfaces

[chrisknvidia]

Part of #399

Scope

This draft implements the hooks-only first slice of issue #399:

• BH1 inventories active bundled hook execution surfaces with runtime-aware matcher, handler, shell, argv, and source semantics.
• BH2 correlates sensitive prompt, event, credential, and file sources with concrete outbound sinks across direct handlers and bounded referenced scripts.
• Cache-only traversal, root and archive isolation, sanitized evidence, deterministic chain digests, fail-closed limits, ledger ownership, scoring, reporting, CLI output, and baseline invalidation are included.

BH3 permission analysis is intentionally excluded. Current Claude Code plugin-root settings.json supports agent and subagentStatusLine; unsupported permission keys are ignored. A follow-up should scope permission analysis to actual project settings runtime surfaces.

Implementation

• discovers default, manifest, marketplace, project-settings, skill, and command hook declarations
• distinguishes shell form from exec argv form and models wrapper/interpreter option semantics
• models command, HTTP, MCP, prompt, and agent handlers against a Claude Code 2.1.238 semantics snapshot
• follows bounded cache-contained shell, Python, and JavaScript chains and fails closed for unsupported reachable behavior
• preserves deterministic BH1/BH2 findings through meta analysis and guarantees BH2 reaches DO_NOT_INSTALL
• emits flat redacted evidence and exact inspection-ledger ownership across directory and ZIP scans

Verification

• full non-provider CI suite: 3,737 passed, 13 skipped, 4 expected xfails, 57 deselected
• real graph and CLI integration matrix: 19 passed across directory and ZIP inputs, JSON, Markdown, SARIF, terminal, baseline, fatal-incomplete, and bounded large-input cases
• bundled source and marketplace suite: 185 passed
• Ruff lint and format: clean
• mypy on all changed production modules: clean
• package build: skillspector 2.9.6 sdist and wheel built successfully
• independent bounded security review: approved after RED-to-GREEN fixes for wrapper, transport, taint, credential, parser, ledger, output, and performance edge cases

Runtime evidence and remaining gaps

A real local Claude Code 2.1.227 UserPromptSubmit run against a loopback collector confirmed matcher-ignore behavior, identical event JSON over HTTP and command stdin, shell versus exec metacharacter semantics, and dormant non-tool if handlers. Inline, referenced, and marketplace fixtures passed strict validation but were not installed and dispatched live. No Claude Code 2.1.238 binary, interactive trust flow, or live tool-event matrix was available, and Docker was unavailable locally.

The PR remains draft for maintainer review and follow-up discussion of the deferred BH3 scope.