Stable hidden-tool reason codes for deterministic filter diagnostics

[davidahmann]

Problem observed
The inventory pipeline deterministically filters tools by enabled predicates, feature flags, read-only mode, builder filters, and toolset selection. However, there was no stable machine-readable reason API for why a tool was hidden, which forced downstream callers to infer behavior indirectly.

Why it matters operationally
When GitHub permission/scope and server filtering intersect, operators need explicit, convergent diagnostics. Without stable reason codes, automation and audits depend on logs or implicit assumptions, which is brittle and harder to verify across tool inventory, prompts, and execution paths.

Minimal repro

go test ./pkg/inventory -run HiddenTools -count=1

Fix approach
I introduced a shared ordered evaluator for tool visibility and exposed a new HiddenTools(ctx) API that returns first-match hidden reason codes per tool name. Added stable codes for:

• enabled predicate false
• feature-flag block
• read-only mode
• builder filter false
• builder filter error
• toolset disabled

isToolEnabled now reuses the same evaluator, so enablement decisions and hidden diagnostics stay aligned.

Validation evidence

• go test ./pkg/inventory -run HiddenTools -count=1 passed.
• Regression tests cover read-only, toolset, feature-flag, builder-false, and builder-error reasons.
• Existing inventory behavior remains deterministic; this change adds reason visibility without changing filter order.

Open follow-up question for maintainers
Should hidden reason codes remain inventory-internal API surface, or should we also expose them in remote/server-facing diagnostics for clients that request tool visibility explanations?
Inspired by research context: CAISI publishes independent, reproducible AI agent governance research: https://caisi.dev