DottaandClaude Opus 4.8
ab7b85878a
Remove trailing generation-wrapper markup (</content>, plus </invoke> in the tutorial) that had leaked at EOF into eleven committed Phase 7 reference, tutorial, evidence, and OKF-journal files. Sync the stated suite counts in the current-state docs (tutorial, scenario-explorer reference, verification-commands reference, and OKF journal) to the verified results: test:phase7 49, test:browser:phase7 25, docs:validate 73 files / 28 OKF concepts / 5 indexes. Drop a brittle wall-clock timing from the journal. The dated 7F verification evidence and log.md milestone entry keep their point-in-time 45/19 figures on purpose. Add a wrapper-markup guard to docs:validate (via scripts/lib/doc-wrappers.mjs) that fails with the exact file and line when generator envelope tags reappear, plus a node:test regression suite wired into the package test script. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
3.6 KiB
Phase 7 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.
Sources: src/tools/phase7-semantic-tool-catalog.ts,
src/tools/phase7-semantic-tool-types.ts, src/tools/phase7-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 36 tools: 14 always-agent tools and 22 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 (22), 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:
Phase7FakeAgentToolBindingemits{operationId, description, inputSchema, outputSchema}.Phase7CodexToolBindingemits{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/phase7-semantic-tools.test.ts
The "catalog" describe asserts a unique, versioned, provider-neutral catalog and that every optional group is present.