Add entitlement approval gate for task classes

[sroussey]

Introduces a static approval rule for task classes, and makes this package's RAG tasks declare the knowledge base they reach so the rule has something to read.

Why here rather than downstream

The entitlement taxonomy says what a task reaches. It has never answered the question a host actually asks it — given this class, must a person approve before it runs — so every host wanting a gate writes its own, downstream, against a taxonomy that grows here. An id added here inherits a pass from a list nobody downstream remembers to widen. That direction is the bug.

The rule

EntitlementApproval.ts exports INFERENCE_ENTITLEMENTS, entitlementsBeyond, taskClassReach, taskClassNeedsApproval and describeTaskClassReach.

• Matching is exact, not hierarchical, even though entitlementCovers sits next door and looks like the natural choice. An ai:autonomous-egress id minted later must gate the tasks declaring it rather than inherit a pass from an ambient ai. Fail-closed on a new capability is the point.
• A class that cannot be asked for its declaration reads as unknown and gates. Catalogs populate taskClass by cast, so one without the static is reachable; calling through unguarded crashed inside the approval path, and defaulting to an empty list is worse — indistinguishable from a task that genuinely reaches nothing.
• An optional entitlement is kept and rendered may use network:http. This parts company with evaluatePolicy deliberately: that decides whether to allow a run and may ignore reach a task degrades without; this decides what to tell a person before they approve.

entitlementsFromChildren, and what it is not

New static on Task (false) / GraphAsTask (true). It means reach not knowable until run time — the subgraph a GraphAsTask is handed.

It is deliberately not hasDynamicEntitlements, which reads like the same question. A task is dynamic when it refines what it already declares — AiTask sets it to attach the resolved model id to ai:model. 43 tasks in builder's catalog set that flag, every AI task among them; gating on it puts an approval in front of running a model at all.

It is also not set on the five run-time composers in this package (AiChatWithKbTask, ChunkRetrievalTask, ContextBuilderTask, DocumentEnricherTask, HierarchicalChunkerTask). They own fixed, hard-coded children — a TextEmbeddingTask, a CountTokensTask — so their reach is knowable from their own source. Flagging them would print "not declared up front" about a known child set, which is the same misleading prompt in the other direction. They declare the union instead.

The case that motivated it

In the first consumer (workglow-dev/builder#461), six tasks in the system catalog are composed — GraphAsTask, FallbackTask, MapTask, WhileTask, ReduceTask — and each declared nothing statically, so a downstream gate read the empty set as "reaches nothing". A MapTask skill ran whatever subgraph an LLM handed it without asking.

Then the same question turned on this package and found the mirror image: AiTask was the only class in packages/ai/src/task/ overriding entitlements(), and no task anywhere in the repo declared storage:* — the taxonomy had it, EntitlementProfiles granted it, nothing asked for it. taskClassNeedsApproval(KbDeleteTask) returned false, and describeTaskClassReach said "reaches nothing", for a task whose execute() calls kb.delete().

Ten classes now declare what they touch, pinned by tests.

Correction, kept visible

Two of those declarations were wrong in an earlier commit on this branch and are fixed in f2b9ebc. Both came from sweeping for kb.<method>( and matching call-shaped text that was not a call:

• ChunkRetrievalTask was given storage:write for "installing a text index on first hybrid search". It does not. It names installTextIndex inside an error message and never calls it; that method assigns a field rather than touching storage; and hybridSearch throws without an index rather than installing one. It declares storage:read.
• TextRerankerTask was given storage:read. It reaches no knowledge base at all — its ports are query, documents, topK, model, and the only kb. in the file is a comment noting a KB invokes this task. Its override is removed and it is ungated.

Over-declaring costs what under-declaring costs: a prompt saying a reranker touches storage is one people learn to click through, and then the KbDeleteTask prompt stops nobody either. Every remaining declaration was re-checked against an awaited call.

VectorSimilarityTask also now extends Task. It used nothing from GraphAsTask and an earlier commit overrode the inherited composed answer to correct it; reparenting makes the wrong answer unrepresentable and drops two more inherited claims (hasDynamicSchemas, hasDynamicEntitlements) equally untrue of it.

Downstream

workglow-dev/builder#461 consumes these exports and is red until this merges and a release ships — its catalog pins =0.4.8. Merge here → release → bump the pin there.

Verification

• bun scripts/test.ts ai rag task-graph entitlement unit vitest — 176 files, 1,743 passed, 0 failed
• bun run lint (type-aware, --deny-warnings) and bun run format-check — clean
• bun scripts/test.ts --check-sections — new test files reachable by section+kind selection

Run on Node 22.22.2, one below the repo's declared floor of 24; storage-backed sections were left unrun for that reason.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JEFYAGb9D3mWfyhYkmeAvN

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	55.24%	40370 / 73070
🔵	Statements	54.71%	42336 / 77370
🔵	Functions	56.02%	7880 / 14064
🔵	Branches	44.35%	20956 / 47251

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/task-graph/src/task/Task.ts	55%	45.23%	52.45%	56.4%	994-996, 140-156, 180-198, 238-246, 269, 289-307, 315-332, 346, 347, 362, 437, 503, 520-523, 534, 545-556, 569, 575-582, 588, 593, 599-601, 619, 625-635, 642-643, 656-670, 682-686, 705, 728-735, 753-755, 773, 789-790, 804, 808-814, 830, 833, 837, 844-847, 871-880, 904, 921-922, 929-938, 954-973, 995-1035, 1048-1052

Generated in workflow #3430 for commit ce41fe3 by the Vitest Coverage Report Action