Document Fin Agent replying status in v2.16

[rahulgdsouza]

Why?

The Fin Agent API's replying status is available on the latest numbered version, not just Preview, so v2.16 consumers need it documented. The spec still described v2.16 as going straight from thinking to awaiting_user_reply.

How?

Adds replying to the /fin/start and /fin/reply status enums, the status lifecycle prose, and the fin_replied event schema in descriptions/2.16/api.intercom.io.yaml; adds the awaiting_user_reply done-signal value to the fin_status_updated event schema, which fires alongside it. Mirrors how Preview documents the same behaviour.

Earlier versions are unchanged — the status is not active below v2.16.

_{Generated with Claude Code}

[shrek-intercom]

❌ PR Review Summary: NEEDS HUMAN REVIEW

	Summary
✅	🎯 Problem — The PR clearly explains the problem (v2.16 spec was outdated with incorrect status transitions) and why it matters, with useful context about the scope of changes.
✅	📝 Alignment — The description accurately captures all substantive changes in the diff, including adding replying to relevant enums and awaiting_user_reply to the fin_status_updated event schema, with only minor supporting edits not explicitly called out.
ℹ️	🧠 Correctness — Disabled for this repository.
❌	🦺 Safety — Changes under descriptions/2.16/ touch the published, frozen public contract, which always requires human review per repo policy, and the semantic changes (deprecation labeling of awaiting_user_reply, updated default example) reinforce the need for oversight.
✅	🚦 Auto-approval — Within size limit (0/150 LOC).

Per-criterion details

Problem

The PR clearly explains the problem (v2.16 spec was outdated, showing wrong status transitions) and why it matters (consumers need accurate documentation). The 'How' section is slightly verbose listing all the specific changes, but it's brief enough and provides useful context about version scope.

Alignment

The PR description claims the following changes, and I'll verify each against the diff:

1. "Adds replying to the /fin/start and /fin/reply status enums" — The diff shows replying added to two endpoint-level status enums (at yaml lines ~4016 and ~4204), which correspond to the /fin/start and /fin/reply response schemas. ✓

2. "the status lifecycle prose" — Line 9 of the diff shows *replying* added to the prose description of Fin's status progression. ✓

3. "the fin_replied event schema" — The diff (lines 52-66) adds replying to the fin_replied event's status enum, changes the description to explain intermediate vs. done-signal semantics, and updates the example to replying. ✓

4. "adds the awaiting_user_reply done-signal value to the fin_status_updated event schema" — Lines 29-41 add awaiting_user_reply to the fin_status_updated event's status enum with a description. ✓

5. "Earlier versions are unchanged" — Only descriptions/2.16/api.intercom.io.yaml is modified. ✓

Additional changes in the diff not explicitly called out in the description:

• The fin_replied event's top-level description text is updated (line 47-48) to explain the new replying/done-signal pattern.
• The tags section documentation for fin_status_updated is updated to include awaiting_user_reply in its parenthetical list (lines 72-73).

These are minor supporting edits fully consistent with the stated changes (adding replying to fin_replied and awaiting_user_reply to fin_status_updated). The description accurately captures all substantive behavioral changes in the diff.

Safety

This PR modifies descriptions/2.16/api.intercom.io.yaml, which falls under the descriptions/2.*/ path pattern. Per the repo-specific safety criteria, any change under descriptions/2.*/ is considered a modification to the "published, frozen public contract" and always requires human review, regardless of whether the changes are additive.

While the changes themselves are largely additive (adding replying to enum values, adding awaiting_user_reply to the fin_status_updated event schema), there is also a change to the fin_replied event's default example value (from awaiting_user_reply to replying) and a description that labels awaiting_user_reply as "Legacy status" — which could signal behavioral deprecation to consumers. These semantic changes to a released version spec warrant human review.

<violated_criteria>
Released version specs — any change under descriptions/2.*/ (the published, frozen public contract) always needs human review.
</violated_criteria>

_{Rate this comment 👍 / 👎 to help us improve 🙏 · Disagree with assessment? Establish ground truth here}