[dimavrem22]

Executive Summary

Support existing WhatsApp groups, readable inline replies, native mentions, and Companion conversations through Codex.

• Keep group media, reactions, explicit quoted replies, and contextual or mention-required participation.
• Show the exact quoted message's author, bounded text, and attachment metadata before the agent responds.
• Use the published SDK 0.7.29 and preserve conversation ordering and durable delivery recovery.

Description

Groups use stable conversation IDs and isolated sessions; names are display labels, not destinations. Native mentions render with the configured agent handle, visible contact name, or verified number in direct and group messages. Companion retains existing Safe/Relaxed behavior and scoped authorization.

Inline reply context resolves only the explicit, authorized parent in the same conversation and identity. It survives queued turns and quiet Companion context without turning quoted mentions or commands into current intent. Optional parent-read failures never block delivery of the current message: transient failures are labeled temporarily unavailable, while inaccessible parents are labeled unavailable. Both retain the exact parent ID without inventing content. Quiet Companion quote-enrichment authorization failures also produce an unavailable marker rather than stopping later turns; authorization before an actual response remains mandatory. Existing source-authorization retries are unchanged. Per-conversation ordering prevents a slow quote read from being overtaken by a later correction. Existing media, reaction, request-key, and delivery-uncertainty handling remains in place.

Reason

An agent should understand which earlier message a person replied to without guessing or requiring a separate model-directed history lookup, while participating consistently in existing groups.

Decisions

• Existing groups only: Require inbound admission and conversation IDs; no group creation, membership management, or group-name addressing.
• Current-message intent: Only the current author's text and verified native mentions control attention and approvals; quoted content remains data.
• Bounded readable quotes: Include source/parent IDs, author, up to 2,000 text characters, and attachment metadata; do not include attachment URLs or contact memories.
• Scoped access: Resolve the exact parent through the identity's authorized API and preserve existing destination, sponsorship, and explicit-block checks.
• Released dependency: Require SDK 0.7.29 throughout installation and current CI lanes rather than a temporary source checkout.

Testing

• Final quote/Companion regression suite: 63 passed. Actual MCP-interpreter SDK checks and diff checks passed. Latest-head unit, host-contract, SDK, CodeQL, and complete full-stack checks passed.
• Current pushed head: b194442b777e2975383152c42fbf5ce3bfec81dd. All latest-head checks passed, including the complete full-stack workflow. Fable, Opus, and Grok found no remaining blocking findings in the final changes.
• Regression targets include ordinary direct/group quotes, Companion initialization/live/quiet context, real SDK models, distinct-parent bursts, same-conversation ordering, independent conversations, inaccessible parents, non-blocking transient-read fallback, and quoted mention/control isolation.

Related PRs

• 0.7.29: WhatsApp groups, Companion, mentions and onboarding inkbox#237
• feat: support WhatsApp groups, native mentions and Companion hermes-agent-plugin#139
• Support WhatsApp groups, native mentions and Companion conversations claude-code-plugin#85
• feat: WhatsApp group replies and Companion support openclaw-plugin#80
• Support existing WhatsApp groups and Companion turns opencode-plugin#46

Installation and verification

From this reviewed checkout, use the Python environment that runs the existing gateway:

python3 -m pip install 'inkbox==0.7.29' -e .
python3 -c 'from importlib.metadata import version; assert version("inkbox") == "0.7.29"; assert version("codex-plugin") == "0.2.27"'
inkbox-codex doctor
inkbox-codex restart
inkbox-codex status

For an existing systemd installation, restart that service instead of starting a second gateway:

systemctl --user restart inkbox-codex.service
systemctl --user status inkbox-codex.service

Preserve the identity, signing key, configuration, and retained state; do not rerun setup just to upgrade.

Manual verification

1. In an existing group, quote an earlier message and send an ambiguous follow-up such as “What about this?” Confirm the agent identifies the exact quoted author and content.
2. Send two rapid replies to different parents, then a plain correction. Confirm each parent remains associated with its source and the correction is not overtaken.
3. Quote an attachment-only message; confirm the context names the attachment without claiming its contents were viewed.
4. In mention-required mode, quote a message containing an agent mention or command without mentioning the agent in the current text. Confirm it stays contextual and does not execute the quoted command.
5. Exercise media, reactions, explicit quoted sends, and Companion Safe/Relaxed participation. Confirm replies stay in the intended group and uncertain operations retain their original keys.

[dimavrem22]

Implemented in 48ba872cd2561810321122802f38e3736e5695d8.

• Existing-group routing, shared mention mode, saved group tool context, current-participant checks, media/quote/reaction support, and no group creation.
• Current-head focused checks: 87 passed with SDK 0.7.29; 154 passed and two group-model integration cases skipped with SDK 0.7.27. The skipped cases passed with the group-capable SDK.
• Installed plugin 0.2.27 with SDK 0.7.29 in the authorized local test runtime; startup and HTTP readiness passed. Mention required mode is active.
• Full offline tests, independent reviews, and CI are still in progress. Phone-to-agent group testing is pending; this is not a completed live message roundtrip claim.

[dimavrem22]

Updated in c4661dd6575b5b254db1c36b50f733890e93b4d6.

• Apply current-participant checks to each explicit group destination, including cross-conversation sends and reaction targets.
• Preserve direct messages, permitted cross-group requests, and cancelled-turn protection.
• Focused checks: 93 passed with SDK 0.7.29; 91 passed and two model-integration cases skipped with SDK 0.7.27. The model-integration cases passed with 0.7.29.
• Updating the local test runtime to this commit; running-version verification will follow. Independent review is ongoing; broad checks are not claimed complete.

[dimavrem22]

Local test rollout verified at c4661dd6575b5b254db1c36b50f733890e93b4d6, plugin 0.2.27 with SDK 0.7.29. Process source, authenticated identity, Mention required configuration, model-host startup, and HTTP readiness were verified.

Opus follow-up review found no remaining blocking findings. Fable review remains in progress. Focused current-head results remain 93 passed on SDK 0.7.29 and 91 passed / two model-integration skips on SDK 0.7.27. Broader checks are incomplete; live user group-message testing is next.

[dimavrem22]

Commit 06495a2 adds verified native WhatsApp @mentions to group mention mode. Only an actual boolean mention flag wakes a reply; arbitrary numeric text, truthy strings/numbers, and quoted-message references do not. The flag survives durable turn routing. Existing textual @agent and @handle mentions continue to work.

Also clarified that older SDKs support direct sends but cannot reliably read lists containing group messages.

Validation: 54 focused group and mention-policy tests passed. Latest-head CI is running. This comment does not claim deployment or live-message verification.

[dimavrem22]

Commit e083afb preserves structured WhatsApp mentions in framed group context and durable turn routing. The agent can see known mentioned phone numbers and distinguish unresolved identities without guessing or automatically loading contact memories. Mentioning another participant does not trigger mention-mode replies.

Validation: 55 focused group/mention-policy tests passed. Latest-head CI is running. Deployment verification is tracked separately.

[dimavrem22]

Commit 370e029 renders verified group mention tokens using contact names when available, known phone numbers otherwise, and an explicit unresolved label when identity is unknown. Raw message text remains unchanged in routing and is retained as metadata when the display text differs.

Only the contact name is retained: no contact notes or memories are added. Repeated tokens are handled without partial-number, URL, or email replacements. Mentioning another participant whose contact name happens to be “agent” still does not wake mention mode.

Validation: 60 focused group/mention tests passed. The preceding full WhatsApp regression run passed 316 tests. Latest-head CI is running; deployment verification is recorded separately.

[dimavrem22]

Updated in 5fc9909:

• Native self mentions render as the configured agent handle, not a phone number or contact nickname; original text and verified mention identity remain available.
• Compatible WhatsApp message bursts preserve every source's original/rendered text and structured mentions, including a native agent mention in a later fragment.
• Other-person mentions still do not activate mention-only reply mode.

Validation: 105 focused group, mention-gating, and session/burst tests passed. The preceding head passed all 323 WhatsApp tests; the expanded suite and CI for this head are running. This comment does not assert deployment status.

[dimavrem22]

Follow-up 2a762af removes contact values and exception payloads from the contact-lookup failure diagnostic. A regression verifies mention lookup failures still fall back to the verified phone without leaking that phone through logs.

Validation: all 35 focused WhatsApp group/render/privacy tests passed. The prior 5fc9909 head completed all 325 WhatsApp tests. Latest-head CI is being monitored; no deployment claim is made here.

[dimavrem22]

0e502d9 updates the real-host test HTTP fixture to serve conversation metadata required by destination-policy validation. This fixes the deterministic 404 in three contract cases without changing runtime code or weakening cancellation assertions. All four actual Codex host authority cases passed locally.

On preceding 2a762af, all three unit shards and CodeQL passed; the two failing contract lanes shared this fixture omission. Monitoring the replacement run on this head.

[dimavrem22]

Implemented WhatsApp Companion parity in 02248ea:

• Reuses the ordered, durable Companion inbox and full paginated initialization history, including live-first recovery and duplicate receipts.
• Preserves native mention rendering and Safe/Relaxed response gates. Historical mentions never wake a new turn.
• Revalidates the exact sponsor activation before turns, tool mutations and queued replies. The local sponsored-peer exception applies only to the admitted group, not direct messages or another group.
• Retains source-bound media/reaction/quoted-reply tools and uses stable automatic-reply request keys. Native thread expansion cannot broaden supplied Companion history.

Validation so far: 109 related tests passed, followed by focused additional grant/tool/retry/signature regressions. Broader related suites and latest-head CI remain running. Deployment will be verified separately after the matching API contract is available.

[dimavrem22]

Addressed three verified Companion review findings in 495ca65:

• Strip only a verified leading self-mention token before parsing approval answers and local controls; another person's mention cannot become an approval prefix.
• Preserve the actual current live source and native mention when a live-first initialization snapshot includes it. A snapshot missing that live source stays context-only.
• Keep deterministic request keys for saved final answers, but use distinct keys for repeated interim approval prompts/notices.

Validation: all 48 focused Companion/group regressions passed. Latest-head CI is running; the preceding 02248ea complete CI passed. The staged plugin has not yet been restarted for this Companion rollout.

[dimavrem22]

aac4cd3 addresses the remaining verified review finding: Companion authorization reads now remain in the shared durable drain, not an extra webhook-acceptance step that could persist a receipt and fail before scheduling it. Activation checks still run before turns, WhatsApp mutations, and queued replies.

All 49 focused Companion/group tests passed, including a transient authorization outage that automatically retries the retained receipt exactly once without requiring webhook redelivery. Latest-head CI is running. No Companion plugin rollout is claimed yet.

[dimavrem22]

Latest fix fb254124e37f1b10694f9184b79fb4ddfee0161a prevents history-only initialization from attributing an absent live message’s native mention metadata to another source. Live messages included in the initialization snapshot retain their own metadata and wake behavior.

All 15 focused Companion tests passed. Latest-head Python unit shards, actual-host contract, SDK lanes and CodeQL passed: workflow. Draft live lanes are skipped. The coordinated development restart remains pending; these checks do not claim a completed live rollout.

[dimavrem22]

Verified Grok mention findings fixed in 63f0bea: ordinary WhatsApp approval/stop controls now recognize leading verified native self mentions, without rewriting raw source metadata; numeric agent handles cannot wake on another recipient’s native numeric token. The usual typed @agent/non-numeric handle behavior is preserved.

All 85 focused group/Companion/session regressions passed. The preceding Companion/media fix also passed the broader 384-test WhatsApp/Companion suite. Follow-up model reviews and current-head CI are underway; no corrected development restart is claimed yet.

[dimavrem22]

Follow-up fixes 1b5c2c2 and 95b84df finish retry projection handling: late ingestion can repair reply/thread links, append attachments and refresh native mentions, so these are excluded from immutable receipt identity. The first admitted copy still controls routing, media and wake behavior; changed source ownership/body still conflicts. A regression exercises all these late projections together and proves retained routing/context are unchanged.

All 21 Companion tests passed. Latest-head CI and final model followups are running; deployment remains pending.

[dimavrem22]

Follow-up c4d6e28 moves attachment downloads and mention-name enrichment behind durable Companion receipt admission, so a slow attachment cannot repeatedly time out the webhook or block later delivery. Prepared context is persisted for restart recovery. The same WhatsApp source re-delivered as ordinary after activation replacement is acknowledged without replacing its saved route/grant; immutable content conflicts and fresh authorization checks remain enforced.

All 87 focused regressions passed, including slow-download acknowledgement/dedup and phase-downgrade preservation tests. Final review followups, broader regressions and latest-head CI are running. No corrected development restart is claimed yet.

[dimavrem22]

Final review fixes in 9aaae27: numeric handles no longer interpret a bare @ token as self mention; exact signed phase downgrades retire only pending/failed receipts with no submitted-source, host or saved-reply checkpoint. Concurrent enrichment/pre-submit is fenced, so newer events can proceed without executing the revoked grant. Submitting, sending, uncertain and reply-pending work is preserved.

All 57 focused regressions passed, including the in-flight enrichment race and checkpoint-state preservation. Three narrow model followups, broader regressions and latest-head CI are running. Development restart remains pending those review results.

[dimavrem22]

Follow-up a65b1e9 covers a reproduced revocation race where the original sender leaves before a retry. An inadmissible current roster now reconciles only an already-stored event through the same immutable conflict and unsubmitted-retirement guards; it never admits a fresh invalid input.

All 58 focused tests passed, including both roster-present and sender-left variants of the in-flight enrichment race. The previous full WhatsApp/Companion run passed 395 tests. Latest-head CI and final scoped reviews are running; no development restart claimed yet.

[dimavrem22]

Development rollout verified for plugin c249a36b38502a73980e01f98487e672373ce18e with combined SDK source 6f9fad715abbae8022789cfc1028a0335bf23212. Installed source hashes match both immutable source snapshots. The isolated development process is running the intended release; local and public readiness returned 200 with no pending/blocked Companion receipts. Production was not changed.

The final fix settles older unsubmitted WhatsApp receipts only on a later signed same-scope replacement activation, never on ambiguous authorization/read failures. All 60 focused tests passed; the preceding full WhatsApp/Companion run passed 395 tests. Final narrow model followups and latest-head CI remain in progress. Health verification is not a claim of a live-phone feature test.

[dimavrem22]

Pushed and deployed 275b547356c94e5019972206f4c558364b36979a with SDK source 6f9fad715abbae8022789cfc1028a0335bf23212. The final delta safely settles delayed lower-sequence deliveries from a replaced activation as well as normal arrival order; all 32 Companion regressions passed. Installed source hashes and both local/public readiness were verified. Production remains unchanged.

The live test exposed a separate backend Companion-history endpoint returning 500. The plugin has retained all three incoming receipts, including the verified native mention, and is retrying automatically. No input was replayed, cleared or manually resent. Live response behavior is not yet verified; backend repair is in progress. Latest-head CI and narrow review followups continue in parallel.

[dimavrem22]

Live development roundtrip now verified on exact plugin 275b547356c94e5019972206f4c558364b36979a + SDK 6f9fad715abbae8022789cfc1028a0335bf23212: after the backend history repair, the retained initialization recovered on its normal retry timer, the verified native group mention reached a real Codex host turn, and the correlated outbound WhatsApp reply was delivered. The original pending queue drained. No manual replay, resend or queue clearing was used.

Complete latest-head CI passed: all three Python unit shards, host contracts, SDK lanes and CodeQL. Workflow. Fable and Opus latest delta reviews are clean; final Grok delta closure is still running. This live proof covers native group mention → agent response, not every media/reaction scenario.

[dimavrem22]

Final review loop is closed for current head 275b547356c94e5019972206f4c558364b36979a: verified follow-up reviews by Fable (claude-fable-5-1), Opus (claude-opus-5-5) and Grok (grok-4.7-build) found no remaining P1/P2 in the final deltas. All verified findings were fixed and regression-tested.

Complete latest-head CI is green (workflow). Development runs this exact source with combined SDK 6f9fad71; source hashes, readiness, automatic retained-message recovery, and native group mention → delivered agent reply have been verified. No production change or package publication was performed.

[dimavrem22]

Ready for review at 275b547356c94e5019972206f4c558364b36979a. The entire ready-triggered live pipeline passed: canary, mock/real channels, all five agent-to-agent cases, all three voice legs, external events and the final aggregate. No jobs failed or were skipped in this run. Individual tests retain existing mode gates (mock/real, dedicated external-event suite and non-selected voice modes). The two optional independent CC reply-all cases were skipped because the third controlled test inbox credential is not configured; this coverage is not claimed. All latest-head unit shards, host contracts, SDK lanes and CodeQL also passed.

Complete live workflow · Unit and contract workflow

[dimavrem22]

Updated in 446a58ef35166504a27c8002781fe7ab0a6beb7f: readable authorized inline-reply context, per-conversation arrival ordering, quiet Companion context retention, and published SDK 0.7.29. Quoted text does not affect mention/control gating.

Final quote/retry/Companion regression suite: 58 passed; ordering, quote, group, and Companion suite: 87 passed. Actual MCP-interpreter SDK checks and diff checks passed.

Latest-head CI and final review closure are running. No merge or runtime rollout is claimed by this update.

[dimavrem22]

Updated in b194442b777e2975383152c42fbf5ce3bfec81dd: readable authorized inline-reply context, per-conversation arrival ordering, quiet Companion context retention, and published SDK 0.7.29. Quoted text does not affect mention/control gating.

Final quote/Companion regression suite: 63 passed. Actual MCP-interpreter SDK checks and diff checks passed. Latest-head unit, host-contract, SDK, and CodeQL checks passed; full-stack checks remain pending.

Latest-head CI and final review closure are running. No merge or runtime rollout is claimed by this update.

[dimavrem22]

Updated in b194442b777e2975383152c42fbf5ce3bfec81dd: readable authorized inline-reply context, per-conversation arrival ordering, quiet Companion context retention, and published SDK 0.7.29. Quoted text does not affect mention/control gating.

Final quote/Companion regression suite: 63 passed. Actual MCP-interpreter SDK checks and diff checks passed. Latest-head unit, host-contract, SDK, and CodeQL checks passed; full-stack checks remain pending.

Latest-head CI and final review closure are running. No merge or runtime rollout is claimed by this update.