DottaandClaude Opus 4.8
449e1a25c6
PAP-17039. Both catalog modules now derive their operation set, placement, required claims, and task-mode policy from a single hand-authored source, src/catalog/canonical-operations.ts; neither declares an independent op list. - New canonical-operations.ts is the single 41-op source of truth. tools/ and semantic-tools/ project it and supply only per-surface presentation (title, description, schema, and the scenario-only mock mapping + redaction). A bidirectional parity check fails the build on any drift. - Unify generic_api_request to one claim, test:generic_api_request (test-only, never product coverage); update scenario grants/plan/tests. - One canonical task-mode policy: the live runtime policy unioned with skill_test. Resolves the ledger's 15 task-mode divergences to zero. The live contract golden is byte-identical (allowedModes is not serialized); the live runtime allowedModes gained skill_test for the 9 standard-only ops so the eval harness can drive them. - reconciliation.ts inverts to derive from canonical-operations and recompute the drift ledger: zero claim/mode divergences; the sole surviving divergence is the reviewed intentional input-schema projection (idempotency in-band for the provider, out-of-band for the observable runtime). Focused catalog, scenario, conformance, issue-thread, mock, and package-export suites pass; golden verified byte-identical. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
4.2 KiB
Capability Semantic Tool Catalog
The semantic tool catalog is the transport-neutral surface an agent may call. It is a frozen set of JSON-schema descriptors — no HTTP method, path, or provider detail. Provider-specific shapes are produced only by bindings, so every provider sees the same operation set.
The operation list, placement, required claims, and task-mode policy are
single-sourced from src/catalog/canonical-operations.ts
(CAPABILITY_CANONICAL_OPERATIONS); this catalog is a projection of it that adds
the scenario presentation (titles, descriptions, input schemas, mock mappings,
and redaction). See catalog reconciliation.
Sources: src/catalog/canonical-operations.ts,
src/tools/capability-semantic-tool-catalog.ts,
src/tools/capability-semantic-tool-types.ts, src/tools/capability-tool-bindings.ts,
barrel src/tools/index.ts.
Two dispositions, plus a separate control-plane list
A tool descriptor's disposition is either always_agent_tool or
optional_agent_tool. Control-plane-owned operations are a separate frozen
list, not a disposition — they are never exposed as tools. See
capability disposition and
authorization and exposure.
The catalog holds 37 tools: 14 always-agent tools and 23 optional tools across 10 groups.
Always-agent tools (14)
get_task_context, get_task_history, list_documents, read_document,
list_document_revisions, report_progress, answer_status_question,
finish_task, block_task, request_review, write_document,
request_human_input, register_deliverable, inspect_operation_result.
Optional tools (23), by group
| Group | Tools |
|---|---|
| discovery | search_tasks, list_agents, list_projects, list_goals |
| delegation_dependencies | create_task, set_dependencies |
| governance | list_approvals, request_approval, decide_approval, comment_on_approval |
| cases | list_cases, upsert_case |
| workspace_runtime | get_workspace_runtime, control_workspace_service |
| routines | list_routines, manage_routine |
| company_skills | list_company_skills, sync_company_skills |
| secrets | list_secret_metadata, read_secret_value |
| portability_admin | export_company, administer_company |
| test_escape_hatch | generic_api_request |
Descriptor shape
Each descriptor carries operationId, version (1), title, description,
input/output JSON schemas, disposition, an optional optionalGroup,
requiredClaims, and optionally allowedRoles, taskModes, a sideEffectClass
(read, task_write, company_write, governance, workspace_control,
secret_read, admin, test_escape_hatch), an idempotency level, redaction
rules, and an abstract mockCommandMapping.
The mockCommandMapping is one of context_read, snapshot_read,
semantic_command, operation_result, or mock_extension — describing what
the tool does against the mock, never how a transport would carry it.
Transport neutrality
Bindings, not descriptors, produce provider shapes, both derived from the same
visibleTools.tools array:
CapabilityFakeAgentToolBindingemits{operationId, description, inputSchema, outputSchema}.CapabilityCodexToolBindingemits{type: "function", name, description, strict: true, parameters}.
Because both bindings derive from one array, the fake-agent and Codex operation surfaces are byte-identical. The conformance suite asserts this parity (the 18/18 fake-agent/Codex operation matrix).
Running the tests
pnpm --filter @paperclipai/paperclip-runner exec vitest run \
src/tools/capability-semantic-tools.test.ts
The "catalog" describe asserts a unique, versioned, provider-neutral catalog and that every optional group is present.