faae6b919f
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agents read saved task documents through native tools.
> - Active-task tools use the task bound to the run. Other task tools
require a task UUID.
> - Agents sometimes call the second set with only a document key.
> - The validator rejects the call, but gives no instruction about the
active-task tool.
> - This pull request adds scope instructions to the tool schemas and
returns them for missing required fields.
> - Agents can correct a rejected call. Task selection and permission
checks stay in place.
## Linked Issues or Issue Description
**What happened?**
Two observed document reads sent only `{"key":"sentry-case"}` to
`read_task_document`. Each returned `Invalid tool input: / must have
required property 'taskId'`. Each later retry with a task UUID returned
without an error.
Pattern: [Task reads fail when agents omit
taskId](https://www.braintrust.dev/app/Paperclip/p/Paperclip%20Staging/patterns/703d8c29-6a40-4aa2-b2c6-e2c5c36b5657).
Related PR: #18824 changed document key validation. It does not address
task scope.
**Expected behavior**
The tool contract must state which task it reads. A missing-field error
must include the schema owner's recovery instructions. A retry must
still pass validation and task permission checks.
**Steps to reproduce**
1. Call `read_task_document` through the MCP bridge with only a document
key.
2. Inspect the error sent to the caller.
3. Retry with an authorized task UUID. Confirm the returned document
belongs to that task.
### Hypothesis and thesis for a fix
Hypothesis: generic tool descriptions contribute to confusion between
active-task and explicit-task tools. An agent can also ignore a correct
schema. These tests do not measure the rate of model mistakes.
Thesis: Paperclip owns task scope instructions. Its five explicit-task
tools now describe the required UUID and the active-task alternative.
The two MCP transports return direct missing-property descriptions from
the admitted schema. The transports do not infer task IDs or apply
Paperclip task policy.
Proof: the same HTTP MCP regression fails on baseline
`f673bd3cb5b5b65ec51781e37355e168c3fe8ae4` and passes with the fix. It
still rejects before handler dispatch. An explicit retry reaches the
requested task. An isolated real API and PostgreSQL test checks the
saved revision, active-task selection, malformed UUIDs, and
cross-company denial through both transports.
## What Changed
- Add UUID and active-task guidance to `get_task`, `comment_on_task`,
and the three explicit-task document tools.
- Return bounded, distinct descriptions for up to three direct missing
required fields. Keep ordinary validation errors unchanged.
- Share this formatter between the Runner and OpenCode MCP bridges.
- Add transport regressions, real route and database checks, and tool
documentation.
## Verification
- Baseline red: both transport regressions return only the
required-property error and fail the recovery instruction assertion.
- Candidate green: 58 Runner and OpenCode transport and error formatter
tests pass on Linux with Node 24.22.2.
- Final-head server verification passed all 115 tests: 113 document-key
checks and two real API integration cases.
- The two local integration cases use real MCP HTTP, agent authority,
API routes, and disposable PostgreSQL. They read a selected other task
and its saved revision, read the active task separately, reject missing
IDs for all five tools, reject malformed UUIDs, and return 404 for a
foreign company task.
- Runner TypeScript typecheck and build pass.
- The full server typecheck passed on head
`03a37e9e50896416cfd45be33bf6dbe3e13169df` with
`PAPERCLIP_TYPECHECK_LOW_MEMORY=1 node scripts/typecheck-layers.mjs`.
The first run ended without a compiler diagnostic. Final-head CI passes
and Greptile is 5/5.
- Full preflight stops because cargo is absent. Rust checks were not run
locally.
- One existing delayed-body fetch test failed with a Node 25 fetch
runtime error. All transport tests pass on Node 24. The first
integration attempt used the wrong fixture return shape; the test was
corrected before the passing run.
- CI follow-up: the Runner test program reported four TS18046 errors
because `Response.json()` returns `unknown` under CI typings. Both tests
now declare the response type. `pnpm exec tsc -p tsconfig.test.json
--noEmit` passes, and both transport suites pass again (56 tests). Final
head `ffccebca19fe9e21a097829adc020679ffa7d86c` passes CI and Greptile
5/5.
- Review follow-up: the foreign task now has a saved document with a
distinct body. Both integration cases passed again after this test-only
change. The read must return 404 and must not return that body.
Current-head CI passes and Greptile is 5/5.
- Final CI:
https://github.com/paperclipai/paperclip/actions/runs/42352822739 . All
required jobs passed for `ffccebca19fe9e21a097829adc020679ffa7d86c`.
Greptile is 5/5 with no unresolved review thread.
- Real local API behavior is verified. External model behavior and
deployed recovery are not verified. No merge or deployment is included.
## Risks
- Missing-field errors now contain schema descriptions. The text is
limited to direct properties in the admitted schema, at most three
distinct descriptions and 1,000 characters each.
- Nested schemas and references do not get recovery text. Their
validation errors remain intact.
- Clearer instructions can help callers recover. They do not guarantee
that a model will choose the correct tool.
## Model Used
- OpenAI GPT-6 via Codex, with tool use and code execution. The exact
deployment model ID and context window are not exposed to this session.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: Claude <noreply@anthropic.com>
6.4 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.
Each protocol action is single-sourced in its own module under
src/protocol-actions/. That module owns the action's policy metadata,
documentation, examples, and its live and scenario JSON-schema presentations.
src/catalog/canonical-operations.ts, src/semantic-tools/catalog.ts, and
src/tools/capability-semantic-tool-catalog.ts are compatibility projections;
do not add action definitions to them. See
catalog reconciliation.
Sources: src/protocol-actions/, 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 40 tools: 14 always-agent tools and 26 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.
Active-task document tools use the task bound to the run: call list_documents
with {} and read_document with {key}. The API bridge also exposes
get_task, list_task_documents, read_task_document, write_task_document,
and comment_on_task for explicitly selected authorized tasks. These require
taskId, a UUID from task context, search, or creation. They do not infer a task
from a document key. Their schemas identify the active-task alternative.
MCP bridges return direct required-property descriptions with missing-field
errors, so the caller can correct the request before execution. Validation and
task permissions still apply to every retry.
Optional tools (26), by group
| Group | Tools |
|---|---|
| discovery | search_tasks, list_agents, list_projects, list_goals |
| delegation_dependencies | create_task, reassign_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 | create_skill, update_skill, 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.
Related
Reassigning existing tasks
reassign_task moves another existing company task to an eligible agent. Read
search_tasks first and send the observed expectedAssigneeActorId (nullable)
and expectedStatusVersion, the new assigneeActorId, a handoff reason, and a
stable idempotencyKey. It requires delegation:tasks:assign and production
tasks:assign authorization in standard mode. The same task retains its
documents, dependencies, scope, priority, and history.
The old execution and any live goal must stop before ownership changes. Active work returns to todo; backlog and blocked work retain their status and are not started. An audited reassignment stop does not create a recovery blocker or retry the outgoing run when it ends without a semantic completion result. Assignment changes advance the observed version, including ordinary API changes, to reject stale handoffs. A durable audit receipt makes retries idempotent across caller runs; retrying after failed dispatch repairs the wake with a stable key and an owner/status/version guard.
The current caller task, conversations, human-assigned tasks, completed or
cancelled tasks, and pending reviews cannot be reassigned with this tool. Use
create_task to delegate new work from the current task. A stop failure or
concurrent ownership change fails without applying the handoff.