diff --git a/docs/OFFICIAL-DOCS.md b/docs/OFFICIAL-DOCS.md index 255264d2e..122f904a2 100644 --- a/docs/OFFICIAL-DOCS.md +++ b/docs/OFFICIAL-DOCS.md @@ -74,7 +74,7 @@ components are declared in, not a component, so it has no row. | Tools reference (includes the Monitor tool) | | 2026-08-06 | | Run agents in parallel — compares subagents, agent view, agent teams, dynamic workflows | | 2026-08-10 | | Orchestrate agent teams — experimental, `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | | 2026-08-10 | -| Cross-session messaging — `ListAgents`/`SendMessage`, `crossSessionInbound`; not on native Windows | | 2026-08-10 | +| Cross-session messaging — `ListAgents`/`SendMessage`, `crossSessionInbound`; v2.1.224+ (native Windows v2.1.234+) | | 2026-08-24 | | Manage sessions — resume, branch, transcript storage | | 2026-08-10 | | Checkpointing — what `/rewind` does and does not restore | | 2026-08-10 | | Feature availability — per-feature matrix by model provider and subscription plan (not by host surface — see Platforms) | | 2026-08-10 | diff --git a/docs/PLUGIN-PHILOSOPHY.md b/docs/PLUGIN-PHILOSOPHY.md index 64d86a714..b63032aec 100644 --- a/docs/PLUGIN-PHILOSOPHY.md +++ b/docs/PLUGIN-PHILOSOPHY.md @@ -191,7 +191,7 @@ re-deriving a row. | [Run agents in parallel](https://code.claude.com/docs/en/agents) | Adopt, as a citation | The upstream comparison of every way Claude Code runs multiple agents — subagents, agent view, agent teams, dynamic workflows. Adopted as the [dispatch ladder](#dispatch-ladder)'s canonical index and cited there, never restated, so the menu an author chooses from cannot go stale inside this file. | The page adds or drops a parallelism surface. | 2026-08-10 | | [Feature availability](https://code.claude.com/docs/en/feature-availability) | Adopt, as a citation | Per-feature availability by model provider and subscription plan — the canonical input to the [cross-platform contract](#cross-platform-contract), cited there. Its "platform" sense is the *provider* platform (Anthropic Console, Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, Microsoft Foundry), never the host surface a consumer runs in; that axis is [Platforms and integrations](https://code.claude.com/docs/en/platforms), a separate row below. Copying it is barred by [evidence and validation](#evidence-and-validation): a provider matrix is exactly the volatile table that rule names. | A plugin proposes narrowing its platform support — re-fetch the matrix then, never trust a restatement. | 2026-08-10 | | [Agent teams](https://code.claude.com/docs/en/agent-teams) | Defer | Fails gate 2 and stops there: "Agent teams are experimental and disabled by default", gated behind `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`, with limitations the page states outright — "No nested teams: teammates cannot spawn their own teammates", and `/resume` and `/rewind` do not restore in-process teammates. Defer rather than decline: the gap question stays open while the surface is opt-in and churning, and no plugin may depend on a team meanwhile. | The page drops the experimental warning or the `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` requirement. | 2026-08-10 | -| [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging) | Decline | Fails gate 1: the channel is for "independent sessions that you start and steer yourself", not for a skill dispatching a worker. It could not be a portable rung either — "Claude Code doesn't offer cross-session messaging on native Windows", and it is absent on Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, and Microsoft Foundry. | Either premise moves: the page stops scoping the channel to sessions you steer yourself, or its Availability section stops excluding native Windows or any of those four providers. | 2026-08-10 | +| [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging) | Decline | Fails gate 1: the channel is for "independent sessions that you start and steer yourself", not for a skill dispatching a worker. It could not be a portable rung either — "not available on Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, or Microsoft Foundry". Re-derived 2026-08-24 after the prior trigger's Windows leg fired: native Windows is now supported ("v2.1.234 or later on native Windows"), which removes one portability leg but moves neither surviving premise, so the verdict stands. | Either surviving premise moves: the page stops scoping the channel to sessions you steer yourself, or its Availability section stops excluding any of those four providers. | 2026-08-24 | | [Sessions](https://code.claude.com/docs/en/sessions) | Decline | Fails gate 1. Resume restores "the full history, including tool calls and results" — the authoring story the [inline-template conventions](#inline-template-conventions) exist to withhold, so it is the opposite of a fresh-eyes rung rather than a missing one. A human session-management surface with no plugin-authoring seam. | `sessions` grows a plugin-facing seam: a manifest field, a tool, or skill frontmatter. | 2026-08-10 | | [Platforms and integrations](https://code.claude.com/docs/en/platforms) | Adopt, as a citation | The upstream index of every host Claude Code runs in — CLI, Desktop, VS Code, JetBrains, web, mobile — and the integrations beside them. Adopted as the [cross-platform contract](#cross-platform-contract)'s canonical input for the host axis, which the already-adopted [feature availability](https://code.claude.com/docs/en/feature-availability) does not carry: that page's axes are provider and plan, and it scopes itself to what runs locally — "The Claude Code CLI and everything that runs locally work on every provider." The host axis is load-bearing because a host can withhold the plugin system outright rather than one capability: a Desktop session in WSL 2 lists "connectors and plugins" among features that "aren't available in WSL sessions yet"; on mobile, "commands that only run in the terminal interface, such as `/plugin` and `/resume`, don't work from the app"; Desktop's Cowork tab sources its plugins from claude.ai configuration, "not from the CLI's `~/.claude` directory"; and the VS Code extension carries only a "Subset" of the CLI's "Commands and skills", so a skill this fleet ships may simply not be reachable there. None of those four is restated in the contract — only the rule they establish is. | `platforms` adds or drops a host, or `feature-availability` grows a host-surface axis, which would make this citation redundant. | 2026-08-10 | | [GitHub Enterprise Server](https://code.claude.com/docs/en/github-enterprise-server) | Decline | Does not fail gate 1 by subject — it is a real plugin-distribution surface, "Plugin marketplaces \| ✅ Supported", and the only page in this run that names one. It fails on need. Nothing in this repo documents a GHES-hosted mirror or fork of this marketplace, and no README anywhere ships a full-git-URL install path — the form GHES requires. Census of the 65 plugin READMEs: 54 carry the literal `/plugin marketplace add melodic-software/claude-code-plugins`; 9 carry no install block; `dometrain` points at another github.com marketplace; and `github`, being marketplace-agnostic, uses the placeholder `/`. All of those are the same `owner/repo` shorthand, which the page says "always resolves to github.com" — correct for this marketplace, and the one place the finding could bite: a consumer redistributing the `github` plugin from a GHES-hosted marketplace would follow that README and silently resolve to github.com instead of their own host. The GHES-specific obligations — full git URL, `extraKnownMarketplaces` pre-registration, `hostPattern` allowlisting — otherwise land on a consumer running their own instance, not on this marketplace. | This repo documents a GHES-hosted mirror or fork, or any README gains an install path that is not `owner/repo` shorthand — a full git URL being the form that means a non-github.com host is in play. Also fires if `plugins/github/README.md` starts naming a concrete GHES-hosted marketplace. | 2026-08-10 | diff --git a/plugins/playbooks/.claude-plugin/plugin.json b/plugins/playbooks/.claude-plugin/plugin.json index e27ee6aac..163bfdb53 100644 --- a/plugins/playbooks/.claude-plugin/plugin.json +++ b/plugins/playbooks/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "playbooks", - "version": "0.8.10", + "version": "0.9.0", "description": "Doctrine and knowledge playbooks as on-demand skills, plus a maintainer-facing update skill. boris — Boris Cherny's Claude Code workflow tips (howborisusesclaudecode.com); skill-authoring — Anthropic's internal skill-authoring playbook; fable-5 — Claude Fable 5's operating doctrine (self-authored, no upstream). The boris and skill-authoring packs vendor a verbatim upstream baseline; /playbooks:update drift-checks and syncs those baselines centrally (maintainers).", "author": { "name": "Melodic Software", diff --git a/plugins/playbooks/CHANGELOG.md b/plugins/playbooks/CHANGELOG.md index e0de90ebe..4bcda5d64 100644 --- a/plugins/playbooks/CHANGELOG.md +++ b/plugins/playbooks/CHANGELOG.md @@ -4,6 +4,19 @@ All notable changes to the `playbooks` plugin are recorded here. The `version` i `.claude-plugin/plugin.json` is the delivery vehicle — a consumer receives a change only after that version increases. +## [0.9.0] + +### Added + +- **`fable-5`: named the worker-continuation mechanism (topic + `list-agents-send-message-plugin-fit`).** `context/orchestration.md`'s "worker already oriented + is cheaper than a fresh one" guidance now says how to continue one where a `SendMessage` tool + resolves: address the worker's agent ID, a completed worker auto-resumes without a new `Agent` + invocation, a user-stopped worker returns a refusal, and a "continue"-shaped parameter on the + dispatch tool spawns a second worker rather than resuming the first. Quotes verified 2026-08-24 + against the sub-agents page (raw `.md` channel, latest release 2.1.241 at read time); recheck + trigger: a changelog entry touching subagent resume. + ## [0.8.10] ### Changed diff --git a/plugins/playbooks/skills/fable-5/context/orchestration.md b/plugins/playbooks/skills/fable-5/context/orchestration.md index b1a9f0628..85f96538d 100644 --- a/plugins/playbooks/skills/fable-5/context/orchestration.md +++ b/plugins/playbooks/skills/fable-5/context/orchestration.md @@ -94,7 +94,7 @@ TRIGGER: a wave is dispatched and the next thing you would do is wait for it. - **Dispatch is not a blocking call.** Move to the next piece of your own work that no pending return feeds. Waiting the wave out makes your throughput the slowest worker's — and the slowest worker is usually the one that drifted, so the wait buys a late return you then discard. - **Check in rather than wait out.** Read a running wave against the drift signals below and intervene on what you find: a worker missing context you already hold gets it while its run can still use it, not in the post-mortem after its return is unusable. -- **A worker already oriented on a subject is cheaper than a fresh one.** Where successive subtasks share a subject, continue the worker that holds its orientation instead of spawning a replacement to re-read the same material, which also keeps the wave off the slowest-spawn path. What you save is the re-derivation, not the tokens: a continued worker re-sends its accumulated context either way — billed as a cache read within its cache lifetime, and re-written past it at the five-minute cache-write rate, which is 1.25× base input rather than base input. Subagents get the five-minute TTL even on a subscription, so a worker resumed after a long wave pays that write rate. It still beats a replacement, which pays those same tokens plus the tool turns to rediscover the material ([prompt caching: subagents and the cache](https://code.claude.com/docs/en/prompt-caching#subagents-and-the-cache) and [pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing), verified 2026-08-04). Start fresh when the subject changes, and always for the fresh-context verifier above, whose entire value is holding none of it. +- **A worker already oriented on a subject is cheaper than a fresh one.** Where successive subtasks share a subject, continue the worker that holds its orientation instead of spawning a replacement to re-read the same material, which also keeps the wave off the slowest-spawn path. What you save is the re-derivation, not the tokens: a continued worker re-sends its accumulated context either way — billed as a cache read within its cache lifetime, and re-written past it at the five-minute cache-write rate, which is 1.25× base input rather than base input. Subagents get the five-minute TTL even on a subscription, so a worker resumed after a long wave pays that write rate. It still beats a replacement, which pays those same tokens plus the tool turns to rediscover the material ([prompt caching: subagents and the cache](https://code.claude.com/docs/en/prompt-caching#subagents-and-the-cache) and [pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing), verified 2026-08-04). Start fresh when the subject changes, and always for the fresh-context verifier above, whose entire value is holding none of it. Where a `SendMessage` tool resolves in your session, continuation IS that tool, addressed by the worker's agent ID: "A completed subagent that receives a `SendMessage` auto-resumes in the background without a new `Agent` invocation", and "`SendMessage` doesn't require [agent teams](https://code.claude.com/docs/en/agent-teams) to be enabled" ([sub-agents](https://code.claude.com/docs/en/sub-agents), verified 2026-08-24; recheck: a changelog entry touching subagent resume). Two caveats: a worker the user stopped themselves returns a refusal instead of resuming, and re-invoking the dispatch tool with a "continue"-shaped parameter does not resume anything, it spawns a second independent worker. ## Monitor, intervene, plan for partial failure diff --git a/plugins/session-flow/.claude-plugin/plugin.json b/plugins/session-flow/.claude-plugin/plugin.json index cf5407a30..bfb76ba18 100644 --- a/plugins/session-flow/.claude-plugin/plugin.json +++ b/plugins/session-flow/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "session-flow", - "version": "0.32.6", + "version": "0.33.0", "description": "Session-lifecycle toolkit of fourteen skills: workflow (navigate a staged dev workflow and suggest the next stage), handoff (write a save-point and resume prompt for /clear-and-resume), continue-in-background (delegate the task to a fresh background agent that continues it now — same save-point engine as handoff, delivered by launching a detached claude --bg session seeded with the resume prompt; launches only on explicit user request), keep-going (recover and continue after any interruption OR when live off-thread work looks stalled — inventory off-thread work, inspect its real output, act only on evidence, then continue; after a usage limit lifts it continues rather than summarizing-and-stalling), find-handoff (recover a lost handoff after /clear — when the resume prompt was written but never copied — via a read-only detection ladder: known-location glob of the handoffs dir, then a bounded, recency-ranked transcript scan for the handoff directive and dashed-rail markers, then a confirm-before-resume gate; surfaces only the resume prompt + metadata, never raw transcript content), clean-stop (get to a durable, linked stopping point before the machine may go away — sweep every repo/worktree for uncommitted, unpushed, or PR-less work, push it durable, put breadcrumbs in PR/issue bodies, then give a free-and-clear verdict), retro (structured end-of-session retrospective with transcript metrics and learning codification), running-retro (in-flight retrospective checkpoints that spawn a subagent to analyze the transcript so far and append classified findings to a cumulative running ledger — capture and route only, the live counterpart to retro; also owns a detached-observer substrate that can watch a session out-of-band and run the checkpoint autonomously after the session ends), orient (read-only session orientation — synthesize where we stand, what we are doing, and why, from durable + off-thread state the built-in /recap never sees: ledgers, handoffs, workflow checklists, running-retro ledgers, open PRs and work-items, and git), orchestrate (arm a session or worker with proactive-orchestration imperatives), reanchor (verify a session's working assumptions are still true against live reality — referenced PRs/issues/branches, base-branch drift, renamed/version-drifted surfaces, stale memory-tier files, and the goal a handoff records, compared across the chain so a re-derived goal reports as drift — before building on them), reconcile (retire finished off-thread work and reconcile this session's task ledger with reality — the prune-and-reconcile counterpart to keep-going's resume: inventory the work this session spawned, inspect its real state, retire the finished and close proven-done tasks, auto-settling the finished and gating any kill of still-running work; sibling sessions in the project are reported read-only), setup (check-centric verification of the observer's runtime prerequisites and configuration), and show-options (lay out which skills fit this moment as a ranked, nothing-hidden menu — a shortlist per bucket plus the complete remainder by name, resolved from the full installed catalog rather than the truncated in-context listing, so the human decides and no option is withheld for looking already-done).", "author": { "name": "Melodic Software", diff --git a/plugins/session-flow/CHANGELOG.md b/plugins/session-flow/CHANGELOG.md index 3aa808824..690f2e539 100644 --- a/plugins/session-flow/CHANGELOG.md +++ b/plugins/session-flow/CHANGELOG.md @@ -1,5 +1,30 @@ # Changelog — session-flow plugin +## [0.33.0] + +### Added + +- **`orchestrate`: SendMessage worker-continuation guidance (#3341 follow-on decision, topic + `list-agents-send-message-plugin-fit`).** The priming addendum now names `SendMessage` as the + mechanism behind imperative 4's worker reuse and mid-flight intervention, presence-gated on the + tool resolving in the session, with the three operative caveats (completed workers auto-resume, + user-stopped workers refuse, re-invoking the dispatch tool spawns a second worker instead of + resuming). Export modes still omit the addendum, so the pasted brief stays tool-agnostic. Backing + quotes, version floors (v2.1.191/v2.1.199), the derived deny-rule caveat, and a same-day + empirical probe (two completed subagents resumed by agent ID in a cloud session) land in + `context/sources.md` under "SendMessage worker continuation", verified 2026-08-24 against the + sub-agents and cross-session-messaging pages with the standard recheck triggers. + +### Fixed + +- **`reference/observer.md`: corrected the SendMessage gating claim.** The findings-return channel + previously said reaching a still-running session is "gated behind experimental agent-teams", + which conflated two surfaces: cross-session messaging is its own feature (v2.1.224+, native + Windows v2.1.234+; per the page, once a session meets the requirements it is "on with nothing + to enable"), and only structured team-protocol messages require agent teams. The bullet now quotes and stamps the availability sentence + (verified 2026-08-24) and keeps the design decision unchanged on its surviving grounds: consent, + next-tool-round delivery latency, and the durable ledger as the crash-safe primary. + ## [0.32.6] ### Changed diff --git a/plugins/session-flow/reference/observer.md b/plugins/session-flow/reference/observer.md index 715f90eae..e78ff2357 100644 --- a/plugins/session-flow/reference/observer.md +++ b/plugins/session-flow/reference/observer.md @@ -122,8 +122,17 @@ config overrides — stop the live observer to re-arm with new settings. `/.gitignore` contains `*`; refuses a repo-root memory root; never the consumer's root `.gitignore`). On a `source=resume` re-arm the observer resumes from the prior run's persisted byte offset, so an already-analyzed span is not re-analyzed into a duplicate ledger entry. -- **`SendMessage`** — reserved for the case where findings must reach a still-running session; gated - behind experimental agent-teams and cannot grant consent, so it is not the default. +- **`SendMessage`** — reserved for the case where findings must reach a still-running session. + Reaching another session is cross-session messaging, not an agent-teams surface: "Cross-session + messaging requires Claude Code v2.1.224 or later on macOS, Linux, and WSL 2, and v2.1.234 or + later on native Windows", and "When a session meets the requirements, messaging is on with + nothing to enable" (both verbatim, verified 2026-08-24 against + ; recheck trigger: a Claude Code + changelog entry touching cross-session messaging or its availability). It stays non-default + here on the original grounds that survive the correction: the observer cannot grant consent on + the target session's behalf (the receiver's inbound controls can hold or refuse the message), a + still-running receiver reads it only between tool calls during its active turn, and the durable + ledger is the crash-safe, auditable primary. - **desktop-notification** — not usable: it is bound to Claude Code's own `Notification` events, not arbitrary external triggers, and its OS toast is macOS/Linux only. diff --git a/plugins/session-flow/skills/orchestrate/SKILL.md b/plugins/session-flow/skills/orchestrate/SKILL.md index 65443e090..8941fe4ab 100644 --- a/plugins/session-flow/skills/orchestrate/SKILL.md +++ b/plugins/session-flow/skills/orchestrate/SKILL.md @@ -114,7 +114,13 @@ resolve the session's effort yourself before using it. Feed the value into imperative 7's tier calibration: it is the level a spawn inherits when neither the call nor the agent definition sets one (a definition's own `effort` overrides the session), so its gap from what a subtask needs IS the over-provisioning imperative 7 exists to stop. (`ultracode` reports as -`xhigh`, so it cannot reveal script-held orchestration.) Export modes omit this addendum, a +`xhigh`, so it cannot reveal script-held orchestration.) Where a `SendMessage` tool resolves in +this session, imperative 4's worker reuse and mid-flight intervention run through it, addressed by +the worker's agent ID: a completed worker auto-resumes on message with no new `Agent` call, one +the user stopped themselves returns a refusal instead, and re-invoking the dispatch tool to fake a +continuation spawns a second independent worker rather than resuming the first. Verbatim quotes, +version floors, and the empirical probe: `context/sources.md`, "SendMessage worker continuation". +Export modes omit this addendum, a pasted target reaches none of those surfaces, and the substitution would travel as dead text. ## Tiered delegation, the shape of a deep tree diff --git a/plugins/session-flow/skills/orchestrate/context/sources.md b/plugins/session-flow/skills/orchestrate/context/sources.md index 54e934196..f48b056cd 100644 --- a/plugins/session-flow/skills/orchestrate/context/sources.md +++ b/plugins/session-flow/skills/orchestrate/context/sources.md @@ -79,6 +79,39 @@ All three sub-behaviors are from the Fable 5 prompting guide (verbatim, verified The brief states these model-agnostically on purpose: they are correct standing imperatives for an under-delegating model too. +### SendMessage worker continuation + +The mechanism the priming addendum names for reusing and steering workers, in Claude Code +specifically. All quotes verbatim, verified 2026-08-24 against + (raw `.md` channel, slug confirmed live in +`code.claude.com/llms.txt`, latest release at read time 2.1.241). Recheck trigger: a Claude Code +changelog entry touching `SendMessage`, subagent resume, or cross-session messaging. + +- **Resume, not re-dispatch:** "Claude uses the `SendMessage` tool with the agent's ID or name as + the `to` field to resume it. `SendMessage` doesn't require + [agent teams](https://code.claude.com/docs/en/agent-teams) to be enabled; only structured + team-protocol messages such as `shutdown_request` and `plan_approval_response` do." +- **Completed workers auto-resume:** "A completed subagent that receives a `SendMessage` + auto-resumes in the background without a new `Agent` invocation. The same applies to a subagent + that Claude stopped with the `TaskStop` tool." +- **User-stopped workers refuse (v2.1.191+):** "a subagent you stopped yourself, with `x` in + `/tasks` or an SDK `stop_task` request, doesn't auto-resume. The `SendMessage` call returns a + refusal telling Claude the agent was cancelled." +- **Prefer the agent ID over the name (v2.1.199+):** "`SendMessage` checks that a name still + refers to the same agent it reached earlier in the conversation. If a newer agent has taken the + name, ... Claude Code refuses the send rather than delivering it to the wrong agent". +- **Empirical probe (Tier 0):** in this repository's own cloud session on 2026-08-24, two + completed background subagents (a researcher and a verifier) were each resumed by agent ID via + `SendMessage`, retained their full context, and returned follow-up work without a fresh `Agent` + dispatch, matching the auto-resume quote above. + +Derived caveat, not a verbatim doc claim: a permission deny rule naming `SendMessage` "removes +the `SendMessage` and `ListAgents` tools" +(, verified 2026-08-24), and resume runs +through that same tool per the first quote above, so deny-listing it also forfeits worker +continuation. A session that wants no cross-session messaging but keeps continuation uses that +page's narrower controls (`crossSessionInbound`) instead of the deny rule. + ## Imperative 5 — NESTED SUBAGENTS Re-verified 2026-08-10 against two official surfaces — the prose page