## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents act through Paperclip tools. The runner shows each tool to
the model with an input schema and checks every call against that schema
before it runs
> - Some tool schemas had a root `oneOf`, `anyOf`, `allOf` or
`if`/`then`. `handoff_case` had no top-level `properties` at all
> - Some model hosts convert such a schema into an empty argument list.
The model then calls the tool with no arguments, and the runner rejects
the call as "Invalid tool input"
> - The repeated-failure guard from #21360 does not see these
rejections, because they happen in the runner before the call reaches
the control plane. The model sent the same rejected call again and again
> - This pull request gives every agent-facing tool a plain object
schema with named properties, checks the old cross-field rules with
named errors, and adds a runner-side guard for identical "Invalid tool
input" rejections
> - The benefit is that models on these hosts can see and send the
arguments, and a dropped argument ends in a clear correction or a stop,
not a long loop
## Linked Issues or Issue Description
**What happened?**
In a chat eval cohort with OpenCode and
`openrouter/deepseek/deepseek-v4.1-flash-1017`, the hosts Wafer and
DigitalOcean served most model calls. In the case handoff case,
`handoff_case` arrived with no arguments on all 10 calls across two
cases. The runner rejected each one with "must have required property
idempotencyKey, case, toAgentId, ...". The model's reasoning said that
the tool showed an empty property list. The model fell back to
`call_api`, but the reply waiter had already expired, so the case
failed. In the preserve-draft case, `request_human_input` was rejected 9
times in a row with the same root `then` error.
**Expected behavior**
Every tool that an agent sees has a plain object schema with named
properties, so every host can show its arguments. When the same call is
rejected twice with the same arguments, the model gets a correction that
lists the expected properties. On the third identical call, the model is
told to change the arguments or stop.
**Paperclip version or commit**
`master` at f7ddab8e94.
**Steps to reproduce**
1. Run an OpenCode agent with
`openrouter/deepseek/deepseek-v4.1-flash-1017`, where OpenRouter routes
to Wafer or DigitalOcean.
2. Ask the agent to hand a case to another agent with `handoff_case`.
3. See `handoff_case` arrive with no arguments and get rejected on every
call.
## What Changed
- Add `providerToolSchemaShapeIssues`
(`packages/paperclip-runner/src/contracts/provider-tool-schema-shape.ts`).
It reports a root that is not `type: "object"`, has no `properties`, or
uses `oneOf`, `anyOf`, `allOf`, `not`, `if`, `then`, `else`,
`dependent*` or `$ref`.
- Add inventory tests that run this check on every agent-facing tool:
the live semantic catalog, the semantic action catalog, the Codex tool
specs, `paperclip_finish` and `paperclip_block` (runner), and the
server-only tool definitions (server). Before this change, the runner
test listed 16 entries for 8 tools: `handoff_case`,
`request_human_input`, `read_case`, `update_case`, `create_case`,
`read_workflow`, `update_workflow` and `paperclip_finish`.
- Flatten these 8 schemas. `handoff_case` is now one object with `to`
(optional, `"done"`), and `case` is one object with optional `id` and
`create`. Descriptions on the properties state which fields each variant
needs.
- Add `toolInputVariantError`
(`packages/paperclip-runner/src/contracts/tool-input-variants.ts`). It
checks the former cross-field rules and returns an error that names what
is wrong and how to send the call correctly. For example: `Invalid tool
input for handoff_case: An agent handoff requires toAgentId, phase. To
finish an existing case instead, send to: "done" with
expectedHandoffVersion and expectedIssueStatusVersion.`
- The server runs this check first in
`PaperclipRunnerToolAuthority.execute` and returns `422`. The #21360
guard therefore counts these errors too. Assigned MCP tools and
connector tools are not checked. The runner semantic dispatchers run the
same check after schema validation. The runner MCP bridges run it for
`paperclip_finish`, which never reaches the control plane.
- Add `RepeatedToolInputRejectionGuard`
(`packages/paperclip-runner/src/drivers/repeated-tool-input-rejection.ts`)
and use it in the OpenCode MCP bridge and the runner tool bridge, where
runner-side validation happens. The key is the tool, the canonical
arguments and the error text, separated per MCP session. The second
identical rejection adds the arguments that arrived and the expected
required and optional properties. The third and later identical calls
say that the call was not accepted and that the model must change the
arguments or stop and report the blocker. State is in memory, per
bridge, and capped at 64 entries.
- Regenerate `semantic-tool-contracts.json`,
`semantic-action-catalog.json`, `protocol/manifest.json` and the seeded
eval fixture.
- Add `spec/fixtures/pre-flat-tool-input-schemas.json`: the 8 strict
schemas from the previous release, for the upgrade test.
## Verification
- `cd packages/paperclip-runner && npx vitest run src/contracts
src/catalog src/protocol-actions src/semantic-tools
src/drivers/opencode/mcp-bridge.test.ts
src/drivers/runner-tool-bridge.test.ts`: all pass.
- `cd server && npx vitest run
src/services/native-runtime/tool-input-variant-admission.test.ts
src/services/native-runtime/repeated-tool-failure-guard.test.ts`: 9
passed.
- Red/green:
- The runner inventory test fails on `master` and lists the 16 entries.
It passes after the change.
- The guard test replays the recorded empty `handoff_case` call 4 times
through the real OpenCode bridge. Without the guard, the second call has
no correction and the test fails. With the guard, the second call lists
`required idempotencyKey, case, instructions; optional to, toAgentId,
phase, ...`, and the third says the call was not accepted.
- Negative controls: changed arguments get a fresh error, and a valid
call still runs once.
- Upgrade safety: `tool-input-variants.test.ts` compiles the previous
release's strict schemas from the fixture. For a corpus of valid and
invalid inputs per tool (27 for `handoff_case`), it checks that "flat
schema accepts and `toolInputVariantError` is null" gives exactly the
same result as the old schema. Each tool has accepted and rejected
inputs.
- Generated outputs: `check:semantic-contracts`,
`check:capability-contract`, `check:protocol-coverage`,
`check:capability-inventory`, `check:protocol-manifest` and the replay
golden check pass.
- Rust tests that read the generated contract: see the CI `runner`
checks.
- Paid narrow run: see the comment below.
## Risks
- Previous-release story: tool schemas are not saved run identity. The
OpenCode bridge lists tools again when a session resumes. A durable Rust
run that is already attached keeps the tool catalog it saved, because
re-attaching the same run does not replace the catalog. Every input the
old strict schemas accepted is still accepted, and every input they
rejected is still rejected, so saved calls, receipts and replays carry
forward. No session is reset, and no profile version or provider
`commandDigest` changes. The pack `contractDigest` changes because
`generated/` changed, as it does for any tool contract change.
- A rejected variant now arrives later for the semantic tools: the
server returns `422` instead of the runner bridge rejecting it. The
error text names the problem.
- For `paperclip_finish` on Codex, the advertised schema no longer has
the root conditional. The Rust bridge accepts a `done` result with a
continuation object, and canonical result validation still rejects it,
as before.
- Latency: the advertised schemas of the 8 tools are 1,876 bytes smaller
(23,785 to 21,909), about 470 fewer prompt tokens when all are listed.
Compiling their validators in the bridge takes 164 ms instead of 214 ms
(median of 15). The guard adds one SHA-256 of the canonical arguments
for each rejected call only. Nothing is added before turn start.
## Model Used
- Claude (Anthropic), model ID `claude-opus-5-5`, used through Claude
Code with tool use and code execution.
## 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
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
PRP v1/v2 Contract
The JSON Schema files in schemas/ are the language-neutral source of truth for
Paperclip Runner Protocol versions 1 and 2. The fixtures in fixtures/ define
accepted and rejected compatibility cases.
Compatibility
protocolVersion,fixtureVersion, andevent.schemaVersionare required.- A consumer fails closed when a required version or schema discriminator is not supported.
- A v1 envelope can contain an unknown optional property when its schema marks that object as extensible.
- A consumer ignores an unknown optional property until a later contract gives it meaning.
- A required field, enum value, or typed structured-input field is not optional.
- Question and answer identifiers are stable across the provider boundary.
- Peers negotiate the highest mutually supported protocol version. Existing v1 runners remain compatible but cannot receive v2-only session-goal commands.
The unknown-optional-fields.json fixture must be accepted. The
unsupported-required-version.json fixture must be rejected.
Session goals (v2)
PRP v2 adds a provider-neutral durable session-goal lifecycle. Every v2
capability snapshot includes sessionGoals, even when its availability is
unsupported or policy_disabled. Paperclip sends controls only when the
negotiated capability advertises the corresponding action.
Commands:
session.goal.getsession.goal.setfor objective, status, and optional token budget changessession.goal.clear
Events:
session.capabilities.updatedsession.goal.snapshotsession.goal.updatedsession.goal.cleared
Goal state is separate from Paperclip's company/business goal hierarchy. The
snapshot distinguishes the durable status from workingNow, because an active
goal can be idle between autonomous turns. A runner emits the full capability
and authoritative snapshot after every session open or resume. Missing v1
capability is unsupported; clients do not infer support from an adapter name.
Harness credential updates
auth.credentials.updated is a P0 runner event available in the v1, v2, and v3 event
schemas. Its payload uses paperclip.auth.credentials.updated.v1 and contains
only provider, bindingId, revision, and detection. No tokens, account
identifiers, credential paths, or credential fingerprints are permitted.
An updated consumer opts in with observeCredentials: true in run.prepare,
before session.open. The bundled runner transport opts in for fresh sessions;
set its observeCredentials option to false to disable observation for a
fresh session. Older hosts that omit the field receive no new event. Consumers
must update their schemas before opting in: an event-enum addition is not an
unknown optional property. Existing runner binaries ignore the optional flag
and do not provide observation; absence of an event does not establish support.
The current Unix runner observes native Codex's managed CODEX_HOME/auth.json
and the Codex/Grok ACPX session homes. It uses a non-recursive directory watch
plus a one-second polling fallback, so atomic file replacement is handled.
Grok's initial inline subscription credential is the baseline, allowing a
refresh during launcher startup to be detected. A first valid credential file
without a prior baseline establishes the baseline without claiming a refresh.
Account identity changes also emit updates, even when token values stay the
same, and establish the baseline for later refreshes on the new account.
Hosts must evaluate the current credential through their private credential
channel and account checks; the event does not authorize an account switch.
Metadata-only changes, partial writes, and deletion do not emit updates.
Unsupported harnesses and refreshes retained only in memory need
their own observer or native-hook integration; adding this event does not make
them observable.
bindingId: "harness-auth" identifies the selected harness authentication
within the envelope's normalized session. Revisions increase for that binding
and survive runner restarts and warm run attachments. The baseline fingerprint
and pending event are persisted together in a private runner state file. Source
retries retain the same event identity until the durable PRP outbox accepts it.
Hosts should commit an idempotent reaction or durable work item through
onCommittedEvent before returning and advancing the cumulative ACK.
The bundled transport exposes onCredentialsUpdated(event) for this commit.
It awaits the callback before ACK, including during warm idle, attachment, and
provider cleanup. Callback failures leave delivery unacknowledged for retry;
callbacks must therefore deduplicate by the original source event identity.
When configured, credential updates bypass the turn notification queue.
Paperclip commits them directly to the run log in a separate credential source
namespace, preserving the original PRP envelope and avoiding collisions with
the driver's normalized event sequence. A turn-only notification consumer
cannot reliably handle idle or cleanup updates; use this callback instead.
detection: "credential_store" reports an observed credential change, not proof
that an OAuth refresh succeeded. Multiple changes between observations can be
coalesced; this is not an audit of every refresh exchange. The schema also
allows native_hook for integrations with an explicit signal. Observation
continues during warm idle and checks at turn terminal and close boundaries,
including Grok's private refresh handoff after live-store cleanup. Retained
runner observations enter the durable outbox before a suspend or shutdown
command completes, without draining the provider backlog. A final check after
provider cleanup also enters the outbox and waits for the host ACK. The runner
retains its terminal recovery fence if that delivery fails.
The event authorizes no credential access or write on its own. A host that needs rotated token values must use a separately authorized handoff with its existing account-identity and freshness safeguards. The default Paperclip credential copy-back behavior remains in place.
Scope
The first provider descriptor and adapter fixture cover Codex only. The schemas for provider-neutral events and semantic receipts do not enable those actions. Discovery and authorization are separate contracts.
The conformance manifest records every source file and its SHA-256 digest. Run
pnpm generate:protocol-manifest from this package after a source change. CI
runs the same generator with --check to reject drift. This check also compiles
the JSON Schemas and validates every replay, question, and cross-language
conformance fixture against its declared schema.
The files in fixtures/replay/golden/ are deterministic reducer oracles. Each
accepted replay fixture has a complete session snapshot and a compact parity
summary. pnpm generate:replay-goldens updates them after an intentional
reducer change; package build and CI fail when they drift.
The files in fixtures/local-runner/scripts/ drive the package-local fake
harness. They cover successful, failed, interrupted, interactive, duplicate
terminal, process-cleanup, and oversized-frame behavior without starting a
production adapter.
runtime.activity.recorded is a P1 Runner event in v1, v2 and v3 with exactly
{ namespace, activityKey }. Both opaque identifiers contain 1–160 Unicode code
points and exclude C0 controls and DEL. namespace groups a producer's activity
types; activityKey names an activity within that group. Consumers use the pair
to select a response to activity in the run. The authenticated outer envelope
provides run and session identity, source sequence and emission time. Core resolves
the run's company, task and agent through its existing authorized run binding;
callers cannot supply those identities in the payload. Recording activity does
not independently verify the reported action or grant access to any resource.
The event uses the ordinary durable outbox, acknowledgement and replay contract.
Local clients capture an opaque context with paperclip-runnerd notification-context
before an operation and invoke record-activity CONTEXT NAMESPACE ACTIVITY_KEY
after success. Runner publishes its matching absolute executable as host-owned
PAPERCLIP_RUNTIME_NOTIFICATION_HELPER and the stable endpoint descriptor path
as PAPERCLIP_RUNTIME_NOTIFICATION_CONTEXT. Configured task environment cannot
override either value. Context is invalidated on warm attachment and process
recovery, so a caller cannot attribute a later completion to a different run.
Runner attachment downloads
For native workspace providers, the authenticated controller can send
runner.attachment.download as a PRP v3 command after provider preparation.
The controller authorizes the source and sends turnId, an HTTPS url with
no query or fragment, a short-lived opaque bearer token, byteSize,
sha256 (lowercase hex), and contentType. The controller must choose the
tenant download endpoint and issue a grant redeemable for only the admitted
file during that turn. Keep grants in private controller state.
Runner starts a bounded HTTPS GET with the grant in the Authorization header
and returns { status: "pending", downloadId }. Runner can process Stop while
the GET runs. Runner emits one runner.attachment.settled event with the same
downloadId and a ready or failed status. A ready event includes the local
path only after Runner verifies the complete file.
The path is local to the Runner, uses a random filename, and is valid only
during the bound turn. Runner clears its private download directory on turn
settlement, authority rotation, and shutdown. The next use of that Runner
state directory also clears residue from interrupted processes. The command
supports files through 10 MiB and limits live downloads to 128 files or
128 MiB per turn. Providers should receive only the path and file metadata.
The authenticated session.snapshot result advertises this command with
attachmentDownloadVersion: 1. The tenant controller uses this capability
before issuing a grant. Attachment admission and issuance of grants belong
to the tenant app.