docs: name SendMessage worker continuation, fix cross-session gating drift

[kyle-sexton]

Closes #3353

Summary

Resolves the "should ListAgents/SendMessage get first-class plugin treatment?" question (topic list-agents-send-message-plugin-fit): name SendMessage where the orchestration posture skills already assume it, fix two stale in-repo claims, and adopt nothing else yet. The durable decision record, including the deferred dedicated skill, the declined registry lane, and the wait-on-ListAgents verdict, each with recheck triggers, is graduated into #3353 (the branch's docs/topics/ contract slice was pruned before merge per the topic-docs convention and this repo's contract-slice-prune-gate).

Fix

• session-flow 0.33.0
  • skills/orchestrate/SKILL.md: the priming addendum (omitted from export modes, so the pasted brief stays tool-agnostic) now names SendMessage as the mechanism behind imperative 4's worker reuse and mid-flight intervention, presence-gated on the tool resolving: agent-ID addressing, auto-resume of completed workers, user-stop refusal, and the fake-continuation anti-pattern.
  • skills/orchestrate/context/sources.md: new "SendMessage worker continuation" evidence block with verbatim quotes from the sub-agents page, version floors (v2.1.191/v2.1.199), a derived deny-rule caveat marked as derived (deny removes the tool; resume runs through the tool), and a same-day empirical probe.
  • reference/observer.md: the findings-return bullet claimed cross-session SendMessage is "gated behind experimental agent-teams". That conflated two surfaces; only structured team-protocol messages need agent teams, while reaching another session is cross-session messaging with its own gates. The bullet now quotes and stamps the availability sentence and keeps the durable-ledger decision unchanged on its surviving grounds (consent, between-tool-calls delivery to an active receiver, crash-safety).
• playbooks 0.9.0: skills/fable-5/context/orchestration.md names the continuation mechanism inside the existing worker-reuse guidance, with the same auto-resume/refusal caveats, stamped.
• docs/OFFICIAL-DOCS.md: the cross-session-messaging row said "not on native Windows", stale since v2.1.234 (announced at 2.1.239). It now states the version floors, re-verified 2026-08-24.
• No frontmatter changes anywhere: allowed-tools grants naming these tools are no-ops (they never prompt), and the discovery agents deliberately omit tools: allowlists. babysit-prs needed no edit; its orchestration reference already names the mechanism and anti-pattern. ListAgents remains unreferenced by design.

Verification

• Every stamped claim re-fetched this session over the raw .md docs channel per the upstream-drift fetch route: slugs confirmed live in code.claude.com/llms.txt, page identity checked by first heading, latest release 2.1.241 confirmed from the upstream CHANGELOG, verbatim spans captured before writing (sub-agents lines on resume/auto-resume/refusal/name-check; cross-session-messaging lines on version floors, delivery, deny rules, notify_when_idle).
• Empirical: two completed background subagents in this session were resumed by agent ID via SendMessage and continued with retained context, with no fresh Agent dispatch (matching the auto-resume quote); ListAgents confirmed absent from this cloud session's tool pool.
• Groundwork double-checked by fresh-context verifiers: the exploration artifact passed spot-checks down to line numbers; the research artifact passed independent-corroboration and confidence re-grades after one remediation round.
• markdownlint-cli2, typos, and editorconfig-checker clean on all touched files; both plugin manifests parse with the bumped versions (0.33.0, 0.9.0) and carry changelog entries.
• The contract-slice-prune-gate failure on the first push was addressed by graduating the decision record to Name SendMessage as the worker-continuation mechanism and fix cross-session gating drift #3353 and deleting the slice in the follow-up commit, which is the pass condition the gate names.

Related

• Refs Name SendMessage as the worker-continuation mechanism and fix cross-session gating drift #3353 (also the closing target above; it carries the graduated decision record with recheck triggers)
• docs/conventions/upstream-drift/README.md (the stamp-and-trigger discipline these edits follow)
• docs/conventions/topic-docs/README.md (the contract-tier prune rule the follow-up commit satisfies)
• Upstream pages: https://code.claude.com/docs/en/sub-agents, https://code.claude.com/docs/en/cross-session-messaging

🤖 Generated with Claude Code

https://claude.ai/code/session_016VfnUrWAEqQsQSCRsDW751

[claude]

Claude finished @kyle-sexton's task in 3m 44s —— View job

---

Code Review Complete

• Gather context (PR diff, changed files, CLAUDE.md)
• Load /review:code-review skill instructions
• Run skip gate checks
• Review changed files for correctness/maintainability
• Post findings (inline + summary)

This is a docs-only change (session-flow 0.33.0, playbooks 0.9.0, a new decision record, and one stale-claim fix in OFFICIAL-DOCS.md). No code/tests/error-handling surface to review; scope was internal consistency of the claims, cross-file references, versioning, and adherence to this repo's own docs/conventions/upstream-drift/README.md discipline that the PR explicitly follows.

Findings

1. 🟡 plugins/session-flow/reference/observer.md#L128 — posted inline. The phrase on by default where those gates are met sits right after a closing quotation mark and before the (verified 2026-08-24 …) citation, so it reads as part of the verified/quoted span, but it isn't inside the quote marks and no verbatim text backs "on by default" specifically. This repo's own upstream-drift convention ("No verbatim quote, no claim") is what this PR is otherwise careful to follow — context/sources.md's new "Derived caveat" paragraph in the same diff models the right pattern by explicitly labeling non-quoted additions as derived. Suggest either quoting the "on by default" wording verbatim from the source or labeling it as derived, the same way sources.md does. The same unlabeled phrasing is echoed in the CHANGELOG.md 0.33.0 entry, so fixing the source claim should tighten that line too.

Checked and clean:

• Version numbers (v2.1.191/199/224/234/241) and plugin version bumps (0.8.10→0.9.0, 0.32.6→0.33.0) are internally consistent across plugin.json, CHANGELOG.md, and body text.
• Cross-references between SKILL.md → context/sources.md (heading name match) and orchestration.md's inline citation are accurate.
• docs/topics/list-agents-send-message-plugin-fit/PLAN.md follows the established PLAN.md shape used by sibling topic docs (e.g. shadowed-skill-renames/PLAN.md), including the "Plan: not filled" convention for decisions executed directly.
• No em dashes or other new house-style violations in the added text (checked against the file's pre-existing usage).
• docs/OFFICIAL-DOCS.md row update is consistent with the Adopters table's stated contract for that file (link + date, divergence-at-fetch trigger).

No correctness or maintainability blockers found beyond the one Suggestion-level note above. External URLs/quotes cited in the diff (sub-agents, cross-session-messaging pages) were not independently re-fetched by this review — that verification is author-claimed per the PR description and not restated here as independently confirmed.

[claude]

Claude finished @kyle-sexton's task in 41s —— View job

---

Security review complete

• Gather context (PR diff, changed files)
• Apply skip gate check
• Review changed files for security-relevant surface
• Post final findings

Skip gate triggered: condition 2 — no security-relevant surface.

All 10 changed files are documentation/config-metadata only:

• docs/OFFICIAL-DOCS.md — one table-row text edit (stale version-floor claim → corrected version floors)
• docs/topics/list-agents-send-message-plugin-fit/PLAN.md — new decision-record doc
• plugins/playbooks/skills/fable-5/context/orchestration.md — prose addition naming SendMessage continuation semantics
• plugins/session-flow/reference/observer.md — prose correction of a stale gating claim
• plugins/session-flow/skills/orchestrate/SKILL.md — prose addition to a priming addendum
• plugins/session-flow/skills/orchestrate/context/sources.md — new evidence block with quotes/citations
• plugins/playbooks/.claude-plugin/plugin.json, plugins/session-flow/.claude-plugin/plugin.json — version bumps only
• plugins/playbooks/CHANGELOG.md, plugins/session-flow/CHANGELOG.md — changelog entries only

No code, scripts, GitHub Actions workflows, permission/allowed-tools grants, dependency pins, or executable logic are touched (consistent with the PR description's own claim of "no frontmatter changes anywhere"). There's no injection surface, no auth/access-control logic, no secret handling, and no trust-boundary change in this diff — it's a docs-only correction-and-naming change.

No security issues found.

[github-actions]

Last security-reviewed head: 8f9f052f345ba9c53808c5d27e6c346c07084095. On the next push, the relevance gate compares only the commits since this SHA; delete this comment to force a full re-review.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8f9f052f34

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

Claude has reviewed this PR 3 times. The lane skips further automatic reviews after 5; deleting this comment resets the count.

[claude]

Claude finished @kyle-sexton's task in 2m 6s —— View job

---

Code Review Complete

• Gather context (PR diff, changed files, CLAUDE.md)
• Load /review:code-review skill instructions
• Run skip gate checks
• Review changed files for correctness/maintainability
• Post findings (inline + summary)

This lane previously reviewed this PR at 8f9f052. Two commits landed since then (aaf89d3, ba53933), so this pass focuses on what changed: the contract-slice prune and the PLUGIN-PHILOSOPHY.md re-derivation, and re-checks whether the standing finding from the prior pass was addressed.

New since last review — both prior P2 findings from chatgpt-codex-connector are now resolved:

1. docs/topics/list-agents-send-message-plugin-fit/PLAN.md is fully deleted (commit aaf89d3) — the decision record graduated to Name SendMessage as the worker-continuation mechanism and fix cross-session gating drift #3353 per the PR description, resolving the "registry trigger already fired" comment; there's no longer a stale decision record left behind to contradict.
2. docs/PLUGIN-PHILOSOPHY.md#L194 — the cross-session-messaging gate row is re-derived (commit ba53933): it now reflects that native Windows is supported from v2.1.234+, drops that leg from the portability objection, and correctly still declines on the two surviving grounds (the "sessions you steer yourself" gate-1 failure and the remaining provider exclusions). The verdict, trigger text, and verified-date column are internally consistent with each other and with the same-day docs/OFFICIAL-DOCS.md row update.

Still outstanding (unresolved from the prior review round, not touched by the two new commits):

• plugins/session-flow/reference/observer.md#L128 — already flagged inline by this lane's prior pass on this PR: on by default where those gates are met sits between the closing quote of the verified version-floor sentence and the (verified 2026-08-24 …) citation, reading as part of the stamped/quoted claim, but it's outside the quotation marks and no verbatim span backs "on by default" specifically. This repo's own docs/conventions/upstream-drift/README.md rule ("No verbatim quote, no claim") is what the new context/sources.md block in this same PR models correctly via its explicit "Derived caveat, not a verbatim doc claim" label. Not re-posted as a duplicate inline comment since it's already anchored on this PR from the prior automated pass and neither changed commit touched this file. The same unlabeled phrasing is still present in plugins/session-flow/CHANGELOG.md:23 ("on by default where its gates are met") and would need the same fix.

Checked and clean on the incremental diff:

• docs/OFFICIAL-DOCS.md row and PLUGIN-PHILOSOPHY.md row agree on the new version floors and both carry the 2026-08-24 verified/re-derived date.
• No other files changed since 8f9f052; the full PR diff vs origin/main matches the 10 files listed in the PR description, and the plugin.json/CHANGELOG version bumps (playbooks 0.9.0, session-flow 0.33.0) remain internally consistent.

No new correctness or maintainability blockers introduced by the latest two commits. The one open item is a carry-over from the prior review round and is a Suggestion-level docs-precision note, not a blocker.

[claude]

Claude finished @kyle-sexton's task in 1m 46s —— View job

---

Code Review (/review:code-review)

• Gather context (PR diff since last-reviewed head 8f9f052, changed files, CLAUDE.md)
• Run skip gate checks (does not apply — new commits since last code-review pass)
• Review new commits for correctness/maintainability
• Post findings

This push (ba53933, c7e82fd, plus the earlier aaf89d3 prune) is a follow-up-only round: it directly addresses the two open findings from the prior review round and makes no other substantive change.

Findings: none. Both prior findings are cleanly resolved:

1. Codex's "re-derive the Windows-exclusion policy" (P2) — docs/PLUGIN-PHILOSOPHY.md#L194 now re-derives the Decline verdict from the current page: it drops the stale Windows-exclusion premise, keeps the two surviving premises (session-steer-yourself scoping, the four-provider exclusion), states explicitly that removing the Windows leg doesn't flip the verdict, and updates the recheck trigger to drop the Windows condition. This is internally consistent with the corrected docs/OFFICIAL-DOCS.md#L77 row (both now agree Windows is supported from v2.1.234).
2. My own prior inline finding on the unquoted "on by default" claim — plugins/session-flow/reference/observer.md#L128 now quotes the actual source sentence verbatim ("When a session meets the requirements, messaging is on with nothing to enable") instead of the unattributed paraphrase, matching this repo's own upstream-drift discipline. plugins/session-flow/CHANGELOG.md#L23 mirrors the same corrected wording, as promised in the fix commit.

Checked and clean:

• The docs/topics/list-agents-send-message-plugin-fit/PLAN.md contract slice is fully absent from the final diff (deleted in aaf89d3) — no contract-slice-prune-gate violation remains in this PR.
• No other files changed since the last code-review pass (plugins/playbooks/CHANGELOG.md, orchestration.md, SKILL.md, sources.md, both plugin.jsons are byte-identical to the previously-reviewed head).
• docs/session-flow/CHANGELOG.md line 24 is unwrapped relative to its neighboring lines (cosmetic only) — MD013 (line-length) is explicitly disabled in .markdownlint-cli2.jsonc, so this isn't a lint violation and isn't worth blocking on.

No correctness or maintainability blockers. This PR looks ready from the code-review lane's perspective.