Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
spec(FIX-1701): adopt D1 option A, Claude Code nests under its container
The product owner chose A on #2549: Claude Code stamps the runtime owner
on its top-level items, as Codex and Cursor do, in this same change.
D1, the goal, the rules (BR-6, BR-8), the plan (V0 first, then a
dedicated nesting step with an owned-container test V5, controls, a
patch changeset) and the D1 and what-changes figures follow. D2 is
unchanged; no user doc pages change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019ZDCzhKV2YFRy4LucoHjCx
  • Loading branch information
claude committed Oct 1, 2026
commit 8edeae6a63cb6be090af375bec9bf58bd4b326a4
33 changes: 20 additions & 13 deletions specs/issues/FIX-1701/BUSINESS-RULES.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,10 @@

[Spec](SPEC.md) · [Decisions](DECISIONS.md) · **Rules** · [Plan](PLAN.md) · [Docs](DOCS.md)

The cases, written as rules. Each row is a stamp a harness makes **today** and must still make
after the extract. *Identity* is the runtime's description of where the run sits; *task* and
*owner* are its two scope fields. The *proved by* column is the plan's check.
The cases, written as rules. Each row is a stamp a harness must make after this change. Every
row is today's behaviour except BR-6 and BR-8, which the dedicated nesting step flips ([D1](DECISIONS.md#d1)).
*Identity* is the runtime's description of where the run sits; *task* and *owner* are its two
scope fields. The *proved by* column is the plan's check.

## Inside and outside a task

Expand All @@ -16,13 +17,18 @@ after the extract. *Identity* is the runtime's description of where the run sits

## The owner

**The rule:** every harness item emitted inside an owned container carries that container's
`ownedBy`, Claude Code's top-level items included. That is the documented Container Ownership
contract (`docs/architecture/streaming.md`); a sub-agent box is a nested container, so its items
carry the sub-agent's owner and the box itself carries the outer one.

| # | When | Then | Proved by |
|---|---|---|---|
| BR-4 | Codex or Cursor emits an item while the identity carries an owner | The item carries that owner, with or without a task | V0 |
| BR-5 | Codex or Cursor, and the identity carries no owner | No `ownedBy` key | V0 |
| BR-6 | Claude Code emits a top-level item while the identity carries an owner | **No** `ownedBy` key. Today's behaviour, pinned by name as the known divergence ([D1](DECISIONS.md#d1)) | V0, labelled as the divergence a separate bug will flip |
| BR-7 | Claude Code emits an item inside one of its sub-agents | `ownedBy` is that sub-agent's container, whatever owner the identity carries | V0 + the existing sub-agent nesting tests |
| BR-8 | Claude Code opens or closes a sub-agent container | The container item carries the task id when there is one, and no identity owner | V0 |
| BR-5 | Any of the three harnesses emits an item outside a sub-agent, and the identity carries no owner | No `ownedBy` key | V0 |
| BR-6 | Claude Code emits a top-level item (message, reasoning, tool open and close, error, and every close path) while the identity carries an owner | The item carries that owner. **Changed:** on `main` it carries none. V0 pins today's missing owner first; the nesting step flips exactly these assertions, and from then on the flipped assertions and V5 are the truth | V0 (flipped in S1), V5 |
| BR-7 | Claude Code emits an item inside one of its sub-agents | `ownedBy` is that sub-agent's container, whatever owner the identity carries. Unchanged from `main` | V0 + the existing sub-agent nesting tests |
| BR-8 | Claude Code opens or closes a sub-agent container | The container item carries the task id when there is one, and the identity's owner when there is one. **Changed:** on `main` it carries no owner; it is a top-level item, so it flips with BR-6 | V0 (flipped in S1), V5 |

## Closes and late items

Expand All @@ -41,12 +47,13 @@ after the extract. *Identity* is the runtime's description of where the run sits
## Failure taxonomy

Nothing here can fail at runtime that cannot fail today: the reader is a pure read of a field
that is already there. The failure this issue guards against is silent, at build time — a
stamped field that moved. V0 is the only defence against it, which is why it lands first and
does not change.
that is already there. The failures this issue guards against are silent: a stamped field that
moved during the extract (V0, which lands first and changes only in the nesting step), and a
Claude Code item that still escapes its container (V5).

## Acceptance criteria this issue owns

All three emitters read their scope through `itemScope`; V0 passes unchanged before and after
the extract; V0 fails under both controls in [PLAN → Checks](PLAN.md#checks); V3 reports no
direct scope reader in the three emitters.
All three emitters read their scope through `itemScope`; V0 changes only in its BR-6 and BR-8
Claude Code owner rows, and only in the nesting step; V5 fails on `main` and passes after; the
two controls in [PLAN → Checks](PLAN.md#checks) turn V0 and V5 red; V3 reports no direct scope
reader in the three emitters.
44 changes: 30 additions & 14 deletions specs/issues/FIX-1701/DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ Two decisions are the sign-off surface. Everything else here is context for them

```mermaid
flowchart TD
I["FIX-1701 · one scope reader"] --> D1["D1 · reader returns task and owner<br/>each emitter keeps choosing what it stamps"]
D1 -.->|"rejected"| X1["A · Claude Code nests under the owner<br/>changes what it stamps · a bug fix"]
I["FIX-1701 · one scope reader"] --> D1["D1 · A · reader returns task and owner<br/>all three emitters stamp both<br/>Claude Code nests under its container"]
D1 -.->|"rejected"| X1["keep Claude Code task-only<br/>leaves the nesting bug · owner wants it fixed now"]
D1 -.->|"rejected"| X2["B · reader returns task only<br/>Codex and Cursor stop nesting · breaks the docs"]
I --> D2["D2 · internal to this repo's harnesses"]
D2 -.->|"rejected"| X3["a published harness-author API<br/>a public promise and docs, in a refactor"]
Expand All @@ -18,21 +18,27 @@ flowchart TD
Solid edges are what you're signing. Dashed edges lost, and the label says why.

<a name="d1"></a>
## D1 · The reader returns the task id and the owner; each emitter keeps deciding which it stamps. Claude Code's missing container nesting is a separate bug
## D1 · The reader returns the task id and the owner, and all three emitters stamp both, so Claude Code's top-level items now nest under their owning container

**The owner chose A** ([comment](https://github.com/fixpoint-labs/flow-state-dev/pull/2549#issuecomment-5923400136):
*"The Claude bug fix should happen as part of this change or before. Then seems like A would be
best."*). It ships **in this same change**, one implementation PR, as its own step after the
characterization.

| | |
|---|---|
| **Instead of** | **(A)** Claude Code also stamps the runtime owner on its top-level items, as Codex and Cursor do. **(B)** The reader returns the task id only, and Codex and Cursor stop stamping the owner |
| **Because** | Both A and B change what a harness stamps, and this desk refactors only. They are also not equal: the documented contract (`docs/architecture/streaming.md` → "Container Ownership", `apps/docs/docs/streaming/emitting-items.md`) says every item inside a container carries its owner. Codex and Cursor keep that promise; Claude Code's top-level items break it. So A is a bug fix, and B would break a documented promise in two packages to match the one that breaks it. Neither belongs in a behaviour-preserving extract |
| **Locks in** | Until the bug ships, a Claude Code run inside a container shows its top-level steps outside that container. The characterization pins today's divergence by name, so the bug fix flips one assertion in one package and the reader itself does not change |
| **Instead of** | **(Draft choice)** Claude Code keeps stamping the task only and the nesting bug ships separately. **(B)** The reader returns the task id only, and Codex and Cursor stop stamping the owner |
| **Because** | The documented contract (`docs/architecture/streaming.md` → "Container Ownership", `apps/docs/docs/streaming/emitting-items.md`) says every item inside a container carries its owner. Codex and Cursor keep that promise; Claude Code's top-level items break it. A brings Claude Code into line. B would break the promise in two packages to match the one that breaks it, so it stays rejected. The draft choice kept the refactor pure, at the price of leaving the bug open; the owner priced that differently |
| **Locks in** | Claude Code runs inside a container show their top-level steps inside it. The reader still decides nothing: Claude Code's call site lets a sub-agent's own owner win for items inside that sub-agent, and takes the runtime owner for everything else. The change is no longer behaviour-preserving for Claude Code, so it carries a patch changeset |

![D1: who decides which owner gets stamped. Chosen: each emitter, with the reader returning both. Instead of: A, Claude Code nests under the owner, or B, the reader returns the task only. It comes down to what gets stamped: the chosen option changes nothing; A changes Claude Code's items; B changes Codex and Cursor's and breaks the documented promise. Locks in: Claude Code's nesting stays wrong until its bug ships. Flips if: the owner decides the bug fix must ride with this refactor](figures/d1-owner.svg)
![D1: who decides which owner a Claude Code item gets. Chosen: A, all three emitters stamp the runtime owner, Claude Code nests under its container. Instead of: keeping Claude Code task-only and fixing the bug later, or B, the reader returns the task only. It comes down to Claude Code in a container: A nests it now; the draft choice leaves it outside until a later fix; B puts all three outside. Locks in: one behaviour change, isolated in its own step with its own test. Flips if: the owned-container test shows the nesting breaks a renderer](figures/d1-owner.svg)

It comes down to what gets stamped: the chosen option changes nothing, and each alternative changes a harness.
It comes down to Claude Code in a container: A nests it now, and both alternatives leave it outside.

**What would change my mind:** the product owner wanting the Claude Code nesting fixed in the
same change. Then this stops being a refactor; it moves to a bug-fix desk with a test that runs
Claude Code inside a real owned container.
**What would change my mind:** the owned-container test showing that nesting Claude Code's
top-level items hides something a reader relies on (a renderer that suppresses owned items it
should not). Then the fix needs its own design, and this change falls back to the pure extract
with the bug filed separately.

<a name="d2"></a>
## D2 · The reader is internal to this repo's harnesses, not a published harness-author API
Expand All @@ -58,20 +64,25 @@ It comes down to the promise: publishing commits us to a shape over a field we n
it unchanged.
- **Presence means `!== undefined`, never truthiness.** All three copies test that today; a
truthiness test would drop an empty string the runtime might hand over.
- **Claude Code's sub-agent container item takes the runtime owner; the items inside it keep
the sub-agent's.** The documented nested-container rule says so ("the inner ContainerItem
itself has `ownedBy = outer.instanceId`"). On `main` that container item carries no owner at
all, so it flips with the other top-level items. Derived from the docs, not asked.
- **Core's own emit sites are not converted.** They write `ownedBy: undefined` as a present
key; converting them would change object shape in memory and widen the refactor past the
issue's three emitters. Flagged in [PLAN → Follow-ups](PLAN.md#follow-ups).
- **The item `taskId` is not the task-run link (FIX-1668).** The reader reads the item's
task scope only; it knows nothing of sessions, requests or attempts.
- **Characterization first, in its own commit, green on today's code.** See
[PLAN → Checks](PLAN.md#checks) V0.
- **Characterization first, in its own commit, green on today's code; then the nesting fix as
its own step.** See [PLAN → Checks](PLAN.md#checks) V0 and V5.

## Considered and dropped

| Alternative | Why not |
|---|---|
| A reader that returns task id only, with Codex and Cursor reading the owner themselves | Leaves two of three emitters still reading the runtime field by hand, which is the drift the issue exists to end |
| A reader that takes a "stamp owner?" flag | Moves Claude Code's divergence into the shared reader, where the next harness inherits a knob instead of a decision. The emitter's own call site is the honest place for it |
| A reader that takes a "stamp owner?" flag | Moves a per-emitter choice into the shared reader, where the next harness inherits a knob instead of a decision. Under A every emitter stamps the owner anyway |
| A separate bug PR for the nesting fix, merged first | The owner allowed "as part of this change or before"; the coordinator chose one PR. The dedicated step and its own test keep the behaviour change reviewable inside it |
| Also extracting provenance derivation, which is copied three times too | Real, but not this issue. A separate deepening, flagged in the plan |
| Merging POC #2534 | It was Claude Code-only, folded into #2531, and closed unmerged. Main's `itemFields` is its shape; this issue builds on it |

Expand All @@ -80,5 +91,10 @@ It comes down to the promise: publishing commits us to a shape over a field we n
- **Draft** — framed as a behaviour-preserving extract of three scope copies into one core
reader; the owner question scoped out to a Claude Code bug because the docs make it one;
one PR, characterization first.
- **Revised** — the product owner chose A on the PR
([comment](https://github.com/fixpoint-labs/flow-state-dev/pull/2549#issuecomment-5923400136)),
and the coordinator put it in this same change. D1 now stamps both fields from all three
emitters; the plan adds a dedicated nesting-fix step after V0 with an owned-container test,
and a patch changeset. D2 unchanged.

**Open: none.**
34 changes: 22 additions & 12 deletions specs/issues/FIX-1701/DOCS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,28 @@

[Spec](SPEC.md) · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · **Docs**

## No documentation impact
## No documentation pages change

Nothing a reader of the docs can observe changes. Every item the Claude Code, Codex and Cursor
harnesses emit carries the same `taskId` and `ownedBy` as before, so the streaming pages
(`apps/docs/docs/streaming/emitting-items.md`), the item contract
(`docs/architecture/items.md`, `docs/architecture/streaming.md` → "Container Ownership") and
the three package READMEs stay accurate.
Decided: **no user doc changes.** The one user-visible change is Claude Code coming into line
with what the docs already promise, so there is nothing for a page to start or stop saying.

The new reader is internal ([D2](DECISIONS.md#d2)): it is marked `@internal`, like the
runtime field it reads, and gets no README entry, no reference page and no changeset.
- **The container contract already promises it.** `docs/architecture/streaming.md` →
"Container Ownership" and `apps/docs/docs/streaming/emitting-items.md` → "Container
components" say every item emitted inside a container carries that container's `ownedBy`,
and a nested container's own item carries the outer owner. After [D1](DECISIONS.md#d1),
Claude Code's top-level items and its sub-agent boxes do exactly that. The pages were right;
the harness was wrong.
- **The item contract** (`docs/architecture/items.md`) and the Codex and Cursor READMEs describe
nothing that moves.
- **The Claude Code README and its guide page** (`apps/docs/docs/tools/claude-code-sdk.md`)
were checked for a sentence saying its steps sit outside an enclosing container, or that only
sub-agent items nest. Neither says so: the README lists what becomes an item, and the guide's
mapping table says a sub-agent becomes a container grouping its items, which stays true. The
implementer re-checks at S1 and corrects any such line in the same PR.
- **The release note is the changeset.** A `patch` fragment for `@flow-state-dev/claude-code`
naming FIX-1701 ([PLAN → S6](PLAN.md#surfaces)) tells a consumer that Claude Code runs inside a
container now show their top-level steps inside it. Codex, Cursor and core get none: nothing
they emit changes.

One existing page describes behaviour that Claude Code does not meet today: the container
ownership contract says every item inside a container carries its owner, and Claude Code's
top-level items don't. That is the separate bug [D1](DECISIONS.md#d1) records. The docs are
right and stay as they are; the bug fix brings Claude Code into line with them.
The new reader is internal ([D2](DECISIONS.md#d2)): it is marked `@internal`, like the runtime
field it reads, and gets no README entry and no reference page.
Loading
Loading