docs+descriptor: Surfaces 1+2 substrate-naming + continuation-integration design doc (canonical2 successor of #338)#362
Conversation
…tion design doc Successor PR for #338 (stuck on base flesh_beast_figs/20260424-claude). Lifts the 4 substantive files from #338 head (299ce1f) onto canonical2 (092f502): - docs/design/continuation-integration.md (+217) - docs/plan/surfaces-1-2-substrate-notes.md (+249) - src/agents/system-prompt.ts - src/agents/tools/continue-delegate-tool.ts Closes #338 (stuck-base PR will be closed after this lands).
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 635ea27b8c
ℹ️ About Codex in GitHub
Codex has been enabled to automatically 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 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| throw new ToolInputError("targetSessionKey is descriptor-only in v2.5; runtime in #332"); | ||
| } | ||
|
|
||
| const task = readStringParam(params, "task", { required: true }); |
There was a problem hiding this comment.
Restore targetSessionKey rejection path
continue_delegate now proceeds directly to normal scheduling without handling targetSessionKey, so calls that still include that field (for example from stale prompts/clients or providers that allow extra args) are silently accepted and routed to the caller session instead of failing fast. This is a behavior regression from the previous loud error path and can misdeliver delegated work while returning a misleading scheduled success.
Useful? React with 👍 / 👎.
| ? [ | ||
| 'For requests like "do this in claude code/cursor/gemini" or similar ACP harnesses, treat it as ACP harness intent and call `sessions_spawn` with `runtime: "acp"`.', | ||
| "For Codex conversation binding/control, prefer the native Codex app-server plugin path (`/codex bind`, `/codex threads`, `/codex resume`). Use ACP for Codex only when the user explicitly asks for ACP/`/acp`, or for background child sessions where native Codex runtime spawn is not exposed.", | ||
| 'For requests like "do this in codex/claude code/cursor/gemini" or similar ACP harnesses, treat it as ACP harness intent and call `sessions_spawn` with `runtime: "acp"`.', |
There was a problem hiding this comment.
Keep Codex requests off ACP by default
This guidance now classifies "do this in codex" as ACP harness intent unconditionally, while the prior disambiguation that preferred native Codex binding/control was removed. In deployments with Codex conversation binding, this will route users into sessions_spawn(runtime:"acp") instead of the native Codex path, changing session/thread semantics and breaking expected Codex-control workflows unless the user explicitly asked for ACP.
Useful? React with 👍 / 👎.
PR #338 head dropped the context:"fork" guidance and the Codex-specific ACP paragraph from system-prompt.ts. The corresponding test on canonical2 still asserted the old wording. Updated the two affected expectations: - guides harness requests to ACP thread-bound spawns: drop Codex paragraph expectation; expand harness list to 'codex/claude code/cursor/gemini'. - gates sub-agent orchestration guidance on available tools: drop context:"fork" wording from spawn-only and orchestration assertions. 62/62 system-prompt tests green.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0607934e58
ℹ️ About Codex in GitHub
Codex has been enabled to automatically 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 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| "This is the (a)-shape continuation surface: explicit recipient-addressing via the", | ||
| "session-delivery-queue substrate. The (b)-shape — broadcast/publish-stream addressing where the", | ||
| "dispatcher names an aspect-stream and listeners tune in independently — is tracked in", |
There was a problem hiding this comment.
Remove unsupported recipient-routing guidance from continuation prompt
This new prompt text says continue_delegate is an explicit recipient-addressing surface, but this commit also removes targetSessionKey from ContinueDelegateToolSchema in src/agents/tools/continue-delegate-tool.ts. That mismatch causes delegation-routing calls to be generated without a supported parameter path: strict tool callers can reject the call outright, while permissive callers can silently schedule to the caller session instead of the intended recipient, returning a misleading success.
Useful? React with 👍 / 👎.
…cessor schema lift Per the schema change in this PR, `targetSessionKey` is no longer advertised on the `continue_delegate` tool surface — cross-session addressing was deferred to the (b)-shape evolution tracked in karmaterminal/binary-canticle#11 and the #332 session-delivery-queue substrate. The two prior tests asserted the old descriptor-only behavior (field present + runtime throws "descriptor-only in v2.5") and were red against the lifted schema. Replaces with two assertions that pin the new contract: - `targetSessionKey` is NOT a property on the tool's parameters - tool description points at the (b)-shape lane (binary-canticle#11) Local: 8/8 in continuation-tools-registration.test.ts.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7cfa4ed36a
ℹ️ About Codex in GitHub
Codex has been enabled to automatically 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 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| ? [ | ||
| 'For requests like "do this in claude code/cursor/gemini" or similar ACP harnesses, treat it as ACP harness intent and call `sessions_spawn` with `runtime: "acp"`.', | ||
| "For Codex conversation binding/control, prefer the native Codex app-server plugin path (`/codex bind`, `/codex threads`, `/codex resume`). Use ACP for Codex only when the user explicitly asks for ACP/`/acp`, or for background child sessions where native Codex runtime spawn is not exposed.", | ||
| 'For requests like "do this in codex/claude code/cursor/gemini" or similar ACP harnesses, treat it as ACP harness intent and call `sessions_spawn` with `runtime: "acp"`.', |
There was a problem hiding this comment.
Restore Codex-native routing guidance
This line now treats requests like “do this in codex” as ACP harness intent unconditionally, but the previous Codex-specific exception was removed. In environments that use native Codex conversation bindings (/codex bind/threads/resume), this steers the model to sessions_spawn(runtime:"acp") and starts a separate ACP session instead of continuing the bound Codex thread, which changes session semantics and breaks expected Codex-control flows unless users explicitly ask for ACP.
Useful? React with 👍 / 👎.
| "This is the (a)-shape continuation surface: explicit recipient-addressing via the " + | ||
| "session-delivery-queue substrate (intra-host today). The (b)-shape evolution — " + | ||
| "broadcast/publish-stream addressing across hosts where the dispatcher names an aspect-stream " + |
There was a problem hiding this comment.
Drop unsupported recipient-routing claim from tool description
The description now says continue_delegate is an explicit recipient-addressing surface, but this commit removed targetSessionKey from ContinueDelegateToolSchema and also removed the runtime rejection for that argument in execute. That mismatch causes callers following this guidance to either fail strict schema validation or (when extra args are accepted) get a misleading scheduled success while the delegate still routes to the caller session instead of a recipient session.
Useful? React with 👍 / 👎.
8 headings in surfaces-1-2-substrate-notes.md ended with ':' which violates MD026/no-trailing-punctuation. Stripped the colons. Local: pnpm lint:docs → 0 errors across 451 files.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ea89a47f16
ℹ️ About Codex in GitHub
Codex has been enabled to automatically 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 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
|
||
| > First durable home for cohort design-prose that has been distributed across `#sprites-of-thornfield` since the lich-protocol stabilization push began. Per 🌻 vote (msg `1497780931417870427`), this lives in 🩸's Surfaces 1+2 lane until upstream consensus pulls it elsewhere. | ||
|
|
||
| ## §1 — Scope |
There was a problem hiding this comment.
Remove em dashes from Mintlify doc headings
docs/AGENTS.md explicitly says doc headings should avoid em dashes/apostrophes because Mintlify anchor generation is brittle, but this file introduces section headers like ## §1 — Scope. That can produce unstable/broken anchor IDs for intra-doc and cross-doc section links in published docs, so readers can land on 404-style fragment targets even when the page exists.
Useful? React with 👍 / 👎.
ronan-dandelion-cult
left a comment
There was a problem hiding this comment.
🌊 LGTM. Local verification on /tmp/oc-swim37-canonical2:
- merge into
cael/325-canonical2is clean (no conflicts) - real PR delta: 6 files / +501/-42 (docs lifts + 4 substantive code/test files; the −875 in the branch-log is just stuff already on canonical2 that the branch was rebased past — not part of the merge)
- vitest on merged tree: 3/3 files · 74/74 tests · 36.63s
system-prompt.test.ts,continuation-tools-registration.test.ts,continue-delegate-tool.test.ts
- Substrate-naming + integration design doc reads clean against the Slice-1/Slice-2 surface that's now landed on canonical2
Carry on. — 🌊
ad6ac31
into
cael/325-canonical2
silas-dandelion-cult
left a comment
There was a problem hiding this comment.
🌫️ approving with one note for follow-up.
Net-correct shape. The docs propose targetSessionKey as the v2.5 surface and the tool code DEFERS it to #332's session-delivery-queue substrate. Schema and runtime no longer lie about each other (vs the prior #338 state where the field existed in schema but threw ToolInputError at runtime). Cleaner. The new tool description points at bc#11 for the (b)-shape, which is the right cross-link.
Byte-walked:
docs/design/continuation-integration.md(+219 new) — substrate-pin in front-matter ✅, §6c resolver-function shape with all four edge cases (resolver-drops vs default-drops vs resolver-throws vs string-sugar) ✅, §6d open byte-walk explicitly named as open ✅docs/plan/surfaces-1-2-substrate-notes.md(+252 new) — tag-pin in front-matter ✅, file-anchored proposals at correct line numbers ✅src/agents/system-prompt.ts— (a)/(b) framing preamble lands aboveUse the continue_delegate tool...line ✅, conditional-voice carrier per frond's bc#11 directivesrc/agents/tools/continue-delegate-tool.ts—targetSessionKeyschema field + runtime guard removed; tool description gains the (a)/(b) framing inlinesrc/agents/tools/continuation-tools-registration.test.ts— tests now pin the omission (expect(params.properties).not.toHaveProperty("targetSessionKey")) and the cross-link (expect(tool.description).toContain("binary-canticle#11")). Schema-and-test agree.
One follow-up flag (non-blocking): the design doc still extensively documents targetSessionKey as the proposed v2.5 surface, but the runtime no longer offers it. Future readers of the doc may reach for the field and find it absent. Suggest a short note in §4 of continuation-integration.md saying the field is proposed pending #332 — would prevent the "tool descriptor lied to me" surprise. Can land in a follow-up commit on canonical2 or in #332 itself.
Lift discipline check: PR body says "lifts 4 substantive files" — accurate by file-count, but the net effect is lift-with-net-removal on the tool surface (4 lines added to descriptor, ~14 lines removed from schema/runtime/test). Worth noting in commit messages but doesn't block merge.
CI 92/95 ✅, 0 failures, 3 non-blocking pending. Ready to merge from my side. APPROVED. 🌫️
…pending #332 (#379) Per 🌫 byte-walk follow-up flag (sprites-of-thornfield 2026-04-27): #362 landed the descriptor + system-prompt block but deliberately deferred the targetSessionKey schema field + runtime wiring to #332 (avoiding the prior schema-vs-runtime divergence that stalled #338). The §4 prose still extensively documented the field as a present v2.5 surface, so future readers reaching for it would find it absent. Adds a Status callout at the top of §4 pointing to #332. No semantic changes to the prose below — those still describe the planned v2.5 behavior. Refs #332 #338 #362
…tion design doc (canonical2 successor of #338) (#362) * docs+descriptor: Surfaces 1+2 substrate-naming + continuation-integration design doc Successor PR for #338 (stuck on base flesh_beast_figs/20260424-claude). Lifts the 4 substantive files from #338 head (299ce1f) onto canonical2 (092f502): - docs/design/continuation-integration.md (+217) - docs/plan/surfaces-1-2-substrate-notes.md (+249) - src/agents/system-prompt.ts - src/agents/tools/continue-delegate-tool.ts Closes #338 (stuck-base PR will be closed after this lands). * fixup: oxfmt re-format on lifted docs * test(system-prompt): align expectations with lifted prompt strings PR #338 head dropped the context:"fork" guidance and the Codex-specific ACP paragraph from system-prompt.ts. The corresponding test on canonical2 still asserted the old wording. Updated the two affected expectations: - guides harness requests to ACP thread-bound spawns: drop Codex paragraph expectation; expand harness list to 'codex/claude code/cursor/gemini'. - gates sub-agent orchestration guidance on available tools: drop context:"fork" wording from spawn-only and orchestration assertions. 62/62 system-prompt tests green. * test(continuation): align targetSessionKey expectations with #338-successor schema lift Per the schema change in this PR, `targetSessionKey` is no longer advertised on the `continue_delegate` tool surface — cross-session addressing was deferred to the (b)-shape evolution tracked in karmaterminal/binary-canticle#11 and the #332 session-delivery-queue substrate. The two prior tests asserted the old descriptor-only behavior (field present + runtime throws "descriptor-only in v2.5") and were red against the lifted schema. Replaces with two assertions that pin the new contract: - `targetSessionKey` is NOT a property on the tool's parameters - tool description points at the (b)-shape lane (binary-canticle#11) Local: 8/8 in continuation-tools-registration.test.ts. * docs: oxfmt re-format surfaces-1-2 notes * docs: strip trailing colons from headings (markdownlint MD026) 8 headings in surfaces-1-2-substrate-notes.md ended with ':' which violates MD026/no-trailing-punctuation. Stripped the colons. Local: pnpm lint:docs → 0 errors across 451 files.
…pending #332 (#379) Per 🌫 byte-walk follow-up flag (sprites-of-thornfield 2026-04-27): #362 landed the descriptor + system-prompt block but deliberately deferred the targetSessionKey schema field + runtime wiring to #332 (avoiding the prior schema-vs-runtime divergence that stalled #338). The §4 prose still extensively documented the field as a present v2.5 surface, so future readers reaching for it would find it absent. Adds a Status callout at the top of §4 pointing to #332. No semantic changes to the prose below — those still describe the planned v2.5 behavior. Refs #332 #338 #362
Resurrects same-host continue_delegate return addressing after the #362/#463 deferral was reversed by figs's 2026-05-03 06Z directive, with careful extract + transpose from Cael #355 rather than naive cherry-pick. Adds targetSessionKey, targetSessionKeys, and fanoutMode tree/all across the descriptor, bracket syntax, TaskFlow state, spawn registry, post-compaction path, session-delivery fan-out, tests, RFC §2.4/§C.2-equivalent text, changelog, and journal. Co-authored-by: Cael🩸 <cael.dandelion.cult@hotmail.com> Co-authored-by: Silas🌫 <silas.dandelion.cult@hotmail.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
… (P0; reverses #463 deferral) (#551) * feat(continuation): resurrect cross-session delegate targeting (#550) Resurrects same-host continue_delegate return addressing after the #362/#463 deferral was reversed by figs's 2026-05-03 06Z directive, with careful extract + transpose from Cael #355 rather than naive cherry-pick. Adds targetSessionKey, targetSessionKeys, and fanoutMode tree/all across the descriptor, bracket syntax, TaskFlow state, spawn registry, post-compaction path, session-delivery fan-out, tests, RFC §2.4/§C.2-equivalent text, changelog, and journal. Co-authored-by: Cael🩸 <cael.dandelion.cult@hotmail.com> Co-authored-by: Silas🌫 <silas.dandelion.cult@hotmail.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(journal): record resurrection PR handoff (#550) Records the pushed implementation SHA, PR URL, validation summary, and final handoff notes for the resurrect-continue-delegate workorder. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * chore(resurrect): remove dev-detritus tmp-drop-me-resurrect.md (#551) Per cohort cleanup note from 🌫 Silas's byte-walk on PR #551: tmp-drop-me-resurrect.md was committed as part of the resurrection lane journal but represents dev-detritus per figs's "no dev detritus" canon. The file was lane-internal scratch; cohort byte-walks complete and the work is captured in the commit history + PR body. Removes the file from tree. The .gitignore upgrade for tmp-drop-me-* remains queued as a separate followup. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(rfc): polish continuation signal RFC Applies figs feedback pass to remove dev-detritus, elevate targeted return routing, and expand lich/future-direction sections. Co-authored-by: Cael🩸 <cael.dandelion.cult@hotmail.com> Co-authored-by: Silas🌫 <silas.dandelion.cult@hotmail.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(rfc): drop D.1 illustrative-vs-exact TODO (figs confirmed illustrative is fine) Per figs 2026-05-03 ~09:01Z dismissal. §D.2's evidence-locations table already points readers to src/auto-reply/continuation/context-pressure.ts for exact source, so D.1's labeled-illustrative pseudocode is the right shape for the technical-paper register. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(ci): resolve pr551 type errors Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * test(ci): fix PR #551 shard failures * test(ci): update channel setup expectations --------- Co-authored-by: frond-scribe <frond-scribe@karmaterminal> Co-authored-by: Cael🩸 <cael.dandelion.cult@hotmail.com> Co-authored-by: Silas🌫 <silas.dandelion.cult@hotmail.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Successor PR for #338 (stuck on base
flesh_beast_figs/20260424-claude).Lifts the 4 substantive files from #338 head (
299ce1f286) onto canonical2 (092f502032):docs/design/continuation-integration.md(+217)docs/plan/surfaces-1-2-substrate-notes.md(+249)src/agents/system-prompt.ts(~17 LOC)src/agents/tools/continue-delegate-tool.ts(~19 LOC)Total: +482/-20 across 4 files.
Why a successor
#338's base is a stuck-fork branch (
flesh_beast_figs/20260424-claude); canonical2 has advanced 9+ merges past it today. Per 🩸's earlier call: replay-small-surface-PR off current canonical2 head, close #338 stuck-base after this lands.Verification
tsc --noEmit --skipLibCheckon the two touched .ts files): no errors.tsc -p tsconfig.core.jsonerrors are pre-existing on canonical2 (model-compatsupportsLongCacheRetentionfield, missing@vincentkoc/qrcode-tuimodule) and unrelated to this lift.Closes #338 once merged.