ORCA-902: regenerate the webhook schema to 2026-09-06

[presmihaylov]

Closes ORCA-902.

Why. The package still bundles the 2026-08-31 schema. Two versions have shipped since, so a customer whose webhook target is on either one gets PlainWebhookVersionMismatchError instead of a parsed payload.

How.

• Look first at the two new tests in parse-webhook.test.ts. Every shape the new fields sit on has additionalProperties: true, so a fixture that merely carries agentStatus or workspaceFiles also passes on the old schema. The checks with teeth are negative, and I confirmed both fail there.
• webhookTargetVersion is a const, so the package holds one version at a time. This is a regen to the latest, not two side by side; two changesets record 2026-09-02 and 2026-09-06, as 1.8.0 did.
• The verify-plain-webhook.test.ts signatures are recomputed: the version bump in the thread-created fixture changes the bytes they sign.

What. Two new events, plus agentStatus on the discussion every discussion event already reports.

type DiscussionToolCallApprovalRequestedPublicEventPayload = {
  eventType: "discussion.tool_call_approval_requested";
  discussion: Discussion;      // agentStatus is TOOL_CALL_APPROVAL_PENDING here
  approvalId: Id;
  toolCallId: string;
  justification: string;
  requestedBy: InternalActor;
  requestedAt: Datetime;
};

type DiscussionToolCallApprovalResolvedPublicEventPayload = {
  eventType: "discussion.tool_call_approval_resolved";
  discussion: Discussion;      // read AFTER the decision settles, so an approved call is IN_PROGRESS
  approvalId: Id;
  toolCallId: string;
  status: "APPROVED" | "DENIED" | "UNKNOWN_APPROVAL_STATUS";
  justification: string;
  reviewerNote: string | null; // required but nullable: the key is always present
  resolvedBy: InternalActor;
  resolvedAt: Datetime;
};

// on Discussion, shared by all four discussion events, optional and not defaulted
agentStatus?: "UNKNOWN" | "IDLE" | "IN_PROGRESS" | "TOOL_CALL_APPROVAL_PENDING" | "UNKNOWN_DISCUSSION_AGENT_STATUS";

// on the discussion.message_created message, optional and not defaulted
workspaceFiles?: { id: Id; fileName: string; fileSizeBytes: number; fileMimeType: string; fileExtension: string }[];

{
  "type": "discussion.tool_call_approval_resolved",
  "payload": {
    "eventType": "discussion.tool_call_approval_resolved",
    "discussion": {
      "id": "thd_01HD44FHDPG82VQ4QNHDR4N2T1",
      "type": "AGENT_SESSION",
      "status": "OPEN",
      "agentStatus": "IN_PROGRESS",
      "threadId": "th_01HD44FHDPG82VQ4QNHDR4N2T2",
      "agent": { "id": "mu_01HD44FHDPG82VQ4QNHDR4N2T3", "publicName": "Support Agent" }
    },
    "approvalId": "agentAppr_01HD44FHDPG82VQ4QNHDR4N2T7",
    "toolCallId": "call_abc123",
    "status": "APPROVED",
    "justification": "Refunding an invoice moves money, so a human should confirm it.",
    "reviewerNote": null,
    "resolvedBy": { "actorType": "user", "userId": "u_01HD44FHDPG82VQ4QNHDR4N2T5" },
    "resolvedAt": "2026-09-06T12:05:00.000Z"
  }
}

---

Note

Medium Risk
Schema version is a hard gate—customers on older webhook targets break until they align SDK and target. New approval events and agent status semantics need correct handler behavior for custom-agent workflows.

Overview
Bumps @team-plain/webhooks from 2026-08-31 to 2026-09-06. The package only accepts payloads whose webhookMetadata.webhookTargetVersion matches that constant, so integrators must upgrade the SDK and move their webhook target forward together or parsePlainWebhook returns PlainWebhookVersionMismatchError.

Discussion / agent updates: discussion.message_created can include optional workspaceFiles on the message (file metadata per entry). agentStatus is added on Discussion for all discussion events (including the new ones). Optional fields are not defaulted by the parser—handlers should use message.workspaceFiles ?? [] and treat missing agentStatus as UNKNOWN.

New webhook types: discussion.tool_call_approval_requested and discussion.tool_call_approval_resolved, with exported payload types and JSON schema definitions. The resolved event always includes reviewerNote (nullable); on resolved events, discussion.agentStatus reflects state after the decision (e.g. IN_PROGRESS after approval).

Tests add fixtures for the new events, negative cases that enforce agentStatus and workspaceFiles shape, and updated HMAC expectations in verify tests after the version bump in fixtures.

^{Reviewed by Cursor Bugbot for commit 6fbae91. Bugbot is set up for automated code reviews on this repo. Configure here.}