A ticket's reasoning can be written over MCP and never read back

[serge-ivo]

MCP can write a ticket's reasoning but cannot read it back

create_instance_ticket takes a reasoning argument and describes it as the audit record
(workers/mcp/src/storage-tools.ts:223):

reasoning: z.string().optional().describe("Why — the decision/audit, shown on the card")

instance_board does not return it. groupBoard builds each card from a fixed field list
(workers/mcp/src/instance-tools/shared.ts:123-132) and maps detail: it.description —
reasoning is absent, and grep -rn 'reasoning' workers/mcp/src/ finds it only in the writer,
in ask_ticket's prose, and in comments. So an agent can file the "why" and no MCP reader can
retrieve it.

Why it matters more after #568

#568 (0172534) fixed the truncation at the writer, so description is no longer silently cut
at 300 chars. That closes the API-side gap — confirmed live. It does not help an MCP caller,
because the fuller text lives in reasoning, which instance_board never returns.

Measured on the delegation card for session csess_e80b6a21 (instance
bd43f4de-ef35-4051-bdec-43f8571414a1): description 375 chars, reasoning 691 chars naming
four trunk pushes plus "and 11 more" — 15 in total. agent_trace(level:"warn") independently
shows 15 act.consequential events between 01:42 and 03:22 on 2026-08-11. A model reading
instance_board sees the short field; the record of what the agent actually did is in the field
it cannot see.

ask_ticket reaches reasoning (instance-tools/board.ts:186), but that is a model call over
one ticket, not a read. There is no way to simply fetch the field.

The decision this needs

Returning reasoning on every card enlarges every instance_board response, and this repo has
been bitten by payload size in both directions — #503 budgeted a payload down rather than
raising a cap, and #569 is open on list_instance_tools returning ~117 KB by default. So do not
just add the field:

1. Return it only on request (an argument), or
2. return it only for cards whose description was derived from it, or
3. return it always and justify the size against a measurement.

State which, and why, with a measured before/after on a real board.

Acceptance criteria

1. An MCP caller can retrieve a ticket's reasoning without a model call.
2. The size decision above is made explicitly and backed by a measured payload delta.
3. A guard asserts that a field the MCP writer accepts is reachable by some MCP reader — stated
   with its denominator per ADR 0002, over the whole write-tool argument set, not a hand-picked
   list. The general asymmetry is the bug; reasoning is one instance of it.
4. The guard fails if reasoning is removed from the read path again.

Verified vs inferred

• Verified: both file:line citations, the grep result, the 375/691 character counts, the
  15 act.consequential events, and that ask_ticket is the only current consumer.
• Inferred: nothing load-bearing. AC3's wider asymmetry is asserted from this one confirmed
  case — whether other written-but-unreadable fields exist is exactly what the guard would
  measure, and is deliberately not claimed here.

[serge-ivo]

Fixed in 4258494 (on main, MCP worker deployed, CI green).

The size decision (your AC2): option 1, return it on request. instance_board takes reasoning: true.

One principle answers this and #569, which was open on the same question at the same time: a default MCP response carries what a reader needs to DECIDE; the long-form evidence behind the decision is fetched on request, through a boolean argument named after the field it returns. #569 spends it on schemas, this on reasoning. Same shape deliberately, so the surface has one convention rather than two.

Backed by measurement, not preference — on a 3-card fixture with 2 cards carrying reasoning it is +1,206 B, +87%.

What is withheld says so. The default response carries reasoningAvailable — a COUNT of the cards that actually have one, so it is a measurement and not boilerplate — plus a note naming the argument. A silently omitted field is unreachable however well the argument is documented; that is how this stayed invisible, and how #566's nextCursor advertised a page nothing could ask for.

Verified live on bd43f4de-…:

• default → no card carries reasoning; reasoningAvailable: 1, note present
• reasoning:true → returned, 691 characters, exactly as you measured
• not truncated: it ends …and 11 more. — on a full stop. The detail on the same card ends …pushed directly to th, cut mid-word, because that row was written before A board card's detail is cut at exactly 300 chars mid-word with no ellipsis — 13 of 15 irreversible acts vanish, and the full text is already on the same card #568's budgeted cut reached production. The two side by side are the clearest demonstration that reasoning passes through whole
• +498 B / +8.18% on this board (1 of 14 cards has reasoning; the ratio scales with how many do)

Worth noting for the record: the card carrying the reasoning is the delegation card deleg-ae7fa3f2-…, not the csess_e80b6a21 session card — that one is still on the board with an empty detail and no reasoning.

AC3 — the general asymmetry, measured

write-readback.test.ts reads the whole surface off the wire and classifies every write-tool argument: 135 published tools, 69 writers, 346 arguments — 223 control, 121 readable, 2 written and not readable.

The 2 are register_instance_runtime.runner_token and upload_resume.content_base64 — a shared secret and binary bytes, both deliberately absent from every reader for the same reason the credentials vault and the Gmail refresh token are. So the answer to the question you declined to guess at is that after this fix there is no other ACCIDENTAL write-only field. You were right not to claim one either way; there wasn't one.

An argument in neither the control set nor the readback table fails the test rather than being skipped — that is what makes the denominator real, and it caught one while being written (delete_instance_connector_grant.grant_id). A second arm holds every declared reader to being a published, read-only tool, so the table cannot decay into prose or quietly point at a writer.

Its honest limit is stated in the file: it proves the question was asked of all 346 arguments; it cannot prove a declared answer is true, because "does reader R return field F" is not statically decidable from a worker that cannot import workers/api. reasoning gets that second proof by driving the tool (board-reasoning.test.ts).

AC4 — proven by reintroducing each defect: dropping reasoning from groupBoard fails two arms; marking it null fails the regression arm; naming a write tool as its reader fails the reader arm.

Version bumped 0.1.1 → 0.1.2 (an input schema changed).

Closing.