paperclipai/paperclip · error

Invalid semantic result

Error message

Invalid semantic result

What it means

When OpenCode invokes the Paperclip terminal tools (`prp_completion` / `prp_block`), the tool arguments must validate against the PRP structured run-result schema via `validatePrpStructuredRunResult`. Malformed arguments — missing fields, wrong types, invalid completion claim — throw this error, meaning the agent emitted a structurally invalid final result.

Source

Thrown at packages/paperclip-runner/src/drivers/opencode/opencode-server-driver.ts:891

    const turnId = this.#activeTurnId;
    if (turnId === null)
      throw new Error("OpenCode tool call is not bound to an active turn");
    this.#emit(
      "item.started",
      {
        kind: "dynamicToolCall",
        item: {
          type: "tool_call",
          id: call.callId,
          name: tool,
          arguments: call.arguments,
        },
      },
      { turnId, itemId: call.callId },
    );
    if (tool === PRP_COMPLETION_TOOL_NAME || tool === PRP_BLOCK_TOOL_NAME) {
      const validation = validatePrpStructuredRunResult(call.arguments);
      if (!validation.ok) throw new Error("Invalid semantic result");
      if (
        (tool === PRP_BLOCK_TOOL_NAME &&
          validation.result.reportedWorkDisposition !== "blocked") ||
        (tool === PRP_COMPLETION_TOOL_NAME &&
          validation.result.reportedWorkDisposition === "blocked")
      )
        throw new Error(
          "Semantic result disposition does not match the terminal tool",
        );
      if (
        validation.result.completionClaim.contractRevision !==
        this.#taskEnvelope.completionContract.revision
      ) {
        throw new Error(
          "Semantic result completion contract revision does not match",
        );
      }
      const fingerprint = canonicalJson(validation.result);

View on GitHub (pinned to 01ad858492)

Solutions

1. Inspect the tool `arguments` in the event stream (`item.started` for the dynamicToolCall) to see which schema field failed validation.
2. Re-prompt or retry the turn: instruct the agent to call the terminal tool with the exact schema from the task envelope's completion contract.
3. Ensure the driver's task envelope schema version matches the agent's instructions — a mismatch between PRP schema versions produces systematic validation failures.
4. Run the same `validatePrpStructuredRunResult` on your side before the agent sends, via prompt-side validation examples, to reduce malformed calls.

Example fix

// before (agent arguments)
prp_completion({ summary: "done" }) // missing completionClaim -> 'Invalid semantic result'

// after
prp_completion({
  reportedWorkDisposition: "completed",
  summary: "done",
  completionClaim: { contractRevision: 2, /* ...required claim fields */ }
})

const check = validatePrpStructuredRunResult(args);
if (!check.ok) throw new Error('agent terminal arguments invalid: ' + check.error);

function isValidSemanticResult(args) { return validatePrpStructuredRunResult(args).ok; }

try {
  await session.dispatchTool({ tool, callId, arguments });
} catch (e) {
  if (e.message === 'Invalid semantic result') {
    // re-prompt the agent with the exact completion-contract schema
  } else throw e;
}

When it happens

Trigger: The agent model calls the completion/block tool with arguments that fail `validatePrpStructuredRunResult`: e.g. omitting `completionClaim`, wrong `reportedWorkDisposition` type, malformed `contractRevision`, or truncated JSON produced by the model.

Common situations: Weaker/smaller models hallucinate the terminal-tool argument shape; a prompt/version change altered the expected result schema but the agent's system instructions still teach the old shape; the agent emits the tool call with prose-wrapped arguments.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Worktree seed manifest is missing source path diagnostics.
• unsupported request schema
• Public attempt must contain the read-only public chat projec
• Unknown public chat payload field
• Unknown public chat projection field

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/82a7e8e59acaa945. Report an issue: GitHub.