kandev/docs/specs/external-question-answering/spec.md

---
status: draft
created: 2026-08-16
revised: 2026-08-20
owner: nova28
---

# External Question Answering — authorized, discoverable, idempotent clarification resolution

> **Revision note (2026-08-20, spec round 6).** This spec was first written against a
> `main` on which nothing made clarification resolution atomic. While it was in Build,
> upstream commit `7e2c4ae84` ("fix: enforce active clarification lifecycle", #2669) merged
> its own approved spec, `docs/specs/clarification-active-lifecycle/spec.md`, which landed an
> atomic current-turn claim and a turn-supersession lifecycle. That work **supersedes this
> spec's entire claim mechanism** — the `clarification_resolutions` table, `ResolveBundle`'s
> own claim SQL, and the workflow-guard changes are all retired here rather than merged
> alongside it. What remains, and what this revision specifies, is the half upstream did not
> build: **authorization**, **out-of-band discovery**, **idempotent replay for a losing
> caller**, and the MCP surface. See *Upstream baseline* for what is already done, and
> *Retired criteria* for the identity of every rule this revision withdraws and why.

## Why

When a Kandev agent calls `ask_user_question_kandev`, the resulting question is answerable in
exactly one place: a popup rendered over the chat input of that task's session. Everything behind
that popup — the durable record, the REST endpoints, the resume path — already exists, but nothing
outside the browser can discover a question or answer it.

This spec makes answering an out-of-band, first-class API. Two new MCP tools on the **external**
surface let a third party (or an agent running outside Kandev) list the questions it may see and
answer one.

Three defects sit under that surface. Upstream has since fixed one of them; the other two are this
spec's load-bearing deliverable.

1. **Atomicity — FIXED UPSTREAM, not by this spec.** `Store.WaitForResponse` deletes the in-memory
   entry the moment it observes `done`, so the old 409 duplicate guard only covered a second answer
   arriving before the winner's waiter woke. Upstream `7e2c4ae84` replaced that with
   `Repository.CompleteActiveClarificationBundle`, a single-transaction row-level claim whose own
   doc comment states *"Exactly one concurrent responder can transition the rows."* This spec
   **consumes** that primitive and adds no second one.

2. **No ownership check — STILL OPEN, this spec closes it.** `POST /api/v1/clarification/:id/respond`
   takes a bare `pending_id`. The global auth middleware attaches identity, but the clarification
   handlers are constructed with only store/repo/message dependencies and never read the context
   identity. Verified against `origin/main` on 2026-08-20: `internal/clarification/handlers.go`
   contains **no** call to any `Authorize*` helper, so the hole is exactly as wide today as when
   this spec was first written, and it covers `GET /:id`, `GET /:id/wait`, `POST /:id/respond` and
   `POST /:id/cancel` alike. Under enforced auth, any PAT holder who learns a `pending_id` can read
   and answer another user's question. This is the one clarification path that bypasses
   `task/service` entirely — `get_task_conversation_kandev`, which reaches the same messages, *is*
   scoped (`ListMessagesPaginated` calls `AuthorizeSessionAccess`).

3. **A losing caller is told the wrong thing — STILL OPEN, this spec closes it.** Upstream's
   `httpRespond` returns **409 "clarification request is no longer active"** when the claim is lost
   (`internal/clarification/handlers.go`, `claimClarificationResponse`). For a human clicking Submit
   twice that is survivable; for a machine answerer racing the browser it is not, because the caller
   cannot tell "someone else answered, here is what they said" from "this bundle is gone". Adding an
   MCP answerer makes that distinction load-bearing.

Adding a second, unauthorized, non-idempotent writer to a surface a third party can reach is the
thing this card must not do. Fixing (2) and (3) on top of upstream's (1) is the deliverable.

## Upstream baseline — already on `main`, not built by this spec

Every statement here was verified by direct read of `origin/main` on 2026-08-20 and is cited so no
builder re-derives it. A builder SHALL treat this section as fact, not as work.

- **`Repository.CompleteActiveClarificationBundle(ctx, pendingID, status, responses)`**
  (`internal/task/repository/sqlite/message_clarification_response.go`) is the claim. It runs one
  transaction: `claimActiveClarificationBundle` issues a single `UPDATE ... SET status='responding'`
  guarded by `pending_id`, `type='clarification_request'`,
  `COALESCE(metadata.status,'') IN ('','pending')`, a **non-terminal session** predicate, a
  **current-turn** predicate, and a malformed-bundle `NOT EXISTS` guard; then it loads the claimed
  rows and writes the terminal metadata. It returns `(messages, claimed bool, error)`.
  `claimed == false` means someone else won or the bundle is no longer active.
- **Terminal status domain is `answered` or `rejected` only.** The function rejects any other value
  with `invalid clarification terminal status`. There is no `cancelled` claim.
- **What the claim writes per message**: `metadata.status = <terminal>`,
  `metadata.response_delivery_pending = true`, and — on `answered` only — `metadata.response = <the
  Answer value for that question_id>`. This is the record from which a losing caller's replay is
  reconstructed (R2).
- **Every claimed message must carry a non-empty `question_id`**;
  `completeClaimedClarificationMessages` returns `clarification message %s is missing question_id`
  otherwise, aborting the transaction.
- **`RestoreActiveClarificationBundle`** rolls a claimed bundle *back* to pending when its detached
  resume could not be dispatched. Upstream's failure philosophy is **roll back and stay answerable**,
  not *record a failure and stay claimed*.
- **`ExpireActiveClarificationBundle`** and **`DetachActiveClarificationMessagesBySessionID`** are
  separate primitives writing `expired` and `agent_disconnected` respectively.
- **The workflow guard is already correct and already widened.**
  `Service.sessionHasPendingClarification` now calls
  `Repository.FindActiveClarificationMessagesBySessionID`, whose predicate is
  `COALESCE(metadata.status,'') IN ('','pending')` **joined to the session's current turn**. The
  function this spec's first version proposed to modify,
  `FindPendingClarificationMessagesBySessionID`, **no longer exists**.
- **Active is upstream's word and upstream's rule.** Per its approved spec: *"A clarification bundle
  is active only when at least one row in the bundle is pending and the bundle belongs to the
  session's current turn."* A **detached** bundle (`agent_disconnected=true`) stays active and
  answerable. A **superseded** bundle (older turn) and a bundle whose **session reached a terminal
  state** are not active; superseded rows *"remain transcript history but cannot drive a chat
  overlay, task/session pending projection, workflow guard, turn-completion detach pass, or late
  agent resume."*
- **Upstream authorization: none.** Confirmed absent, per *Why* item 2.

## Terminology

- **Bundle** — one clarification request: 1..4 questions sharing one `pending_id`.
- **Active** — upstream's rule, quoted above. This spec adopts it verbatim as its membership test
  and does not restate it in its own words (D4).
- **Resolution** — the terminal outcome of a bundle: `answered` or `rejected`.
- **Claim** — `CompleteActiveClarificationBundle` returning `claimed == true`. Exactly one caller
  claims a bundle.
- **Winner** — the caller whose claim succeeded. **Loser** — any later caller for the same bundle.
- **Unscoped caller** — no identity in request context (event bus, pollers, orchestrator) or a
  synthetic identity (auth disabled). Matches `callerScope` in `task/service/service_access.go`.

## Data model

**This spec adds no table and no column.** The `clarification_resolutions` table specified by the
first version of this spec is retired in full (see *Retired criteria*); upstream's claim writes its
terminal state into the existing `task_session_messages.metadata`, and that is now the sole
authority on whether a bundle is resolved.

Two identity rules survive from the first version because **authorization still needs them** — they
were never about the claim.

- **M5. Resolving `task_id` and `session_id` for a bundle.** `session_id` is
  `task_session_messages.task_session_id`, which is `NOT NULL` and FK-constrained, so it is always
  present for a bundle that has durable messages. `task_id` is read from
  `task_session_messages.task_id`, which is `TEXT DEFAULT ''` and **can legitimately be empty**:
  `httpCreateRequest` logs a warning and continues with `taskID = ""` when the session lookup fails,
  so such bundles exist in the wild. When the message's `task_id` is empty, the system SHALL resolve
  it from the bundle's session row (`task_sessions.task_id`, declared `NOT NULL`). Without this rule
  an empty-`task_id` bundle would pass `AuthorizeTaskAccess(ctx, "")` to a lookup that fails for
  every scoped caller **including its own owner**, making it permanently unanswerable.
- **M5a. When neither source yields a `task_id`, the bundle is unresolvable.** Reachable only if the
  session row is missing or its `task_id` is the empty string. Such a bundle SHALL be treated as
  not-found (A5) for every **scoped** caller, and SHALL be **omitted from L1 for every caller,
  including an unscoped one**. It remains answerable by `pending_id` by an unscoped caller whenever
  upstream's claim would still accept it, which preserves single-user behavior.
  The listing half of that decision is deliberate and is the one a builder would otherwise invent.
  Listing it for unscoped callers only would require the L1c join to become an outer join, which in
  turn forces L3's mandatory `task_id` to carry some invented value for that one row — and L3 has no
  such value, so an MCP client parsing the field would meet a `null` or an empty string with no
  stated meaning. Omitting it keeps the L1c join inner, keeps L3's `task_id` always a real task ID,
  and costs nothing that matters: the bundle is still visible to a human in the chat transcript and
  still reachable through `get_task_conversation_kandev`.

### Existing state, unchanged in shape

- **In-memory** `PendingClarification` keeps its role: it is the delivery channel that unblocks a
  still-waiting agent inside its own turn. Upstream already removed its duty as duplicate guard.
- **Durable per-question messages** (`type = 'clarification_request'`) keep their metadata shape
  verbatim: `pending_id`, `question_id`, `question`, `question_index`, `question_total`, `context`,
  `status`, `response` once answered, plus upstream's `agent_disconnected` and
  `response_delivery_pending`. **This spec adds no metadata key and changes no existing one.**

## The resolution operation

A single service-layer operation is the sole entry point for the REST respond endpoint and the MCP
answer tool. It does **not** implement a claim; it authorizes, validates, and delegates to upstream's.

`ResolveBundle(ctx, pendingID, outcome) -> (Resolution, claimed bool, error)`

Ordered steps:

1. **Resolve identity of the bundle.** Read the bundle's durable `clarification_request` messages by
   `pending_id`, deriving `session_id` and `task_id` per M5. If no messages exist, return not-found.
2. **Authorize.** Call `TaskService.AuthorizeTaskAccess(ctx, taskID)`. A denial returns not-found.
3. **Validate the outcome** against the bundle's question set (N6–N8b, per N8c).
4. **Claim, by delegation.** Call `CompleteActiveClarificationBundle(ctx, pendingID, terminal,
   responses)`. `claimed == true` → this caller won; `claimed == false` → R2; a returned error → R4a.
5. **Winner only:** deliver to the in-memory waiter and publish, using upstream's existing
   `RespondWithDeliveryConfirmation` / restore path unchanged (R7).

Steps 1–3 are this spec's addition. Step 4 is upstream's. Step 5 is upstream's, reached unchanged.

- **P1. There SHALL be exactly one claim mechanism in the codebase.** `ResolveBundle` SHALL NOT
  insert, update, or read any claim record of its own, and SHALL NOT gate the claim on any
  precondition upstream's predicate does not already enforce. A second mechanism, however carefully
  coordinated, reintroduces the cross-entry-point race this card exists to close: a REST answer
  claiming one way and an MCP answer claiming another can both win, and no existing test would catch
  it because REST-vs-MCP races could not be written before the MCP tool existed.
- **P1a. What step 4 passes to the claim.** `terminal` SHALL be `answered` or `rejected` and nothing
  else; upstream rejects any other value. `responses` SHALL be a map **keyed by `question_id`**, one
  entry per question in the bundle, whose value is that question's answer entry — the shape
  `completeClaimedClarificationMessages` indexes as `responses[questionID]` and writes verbatim to
  `metadata.response`. For a `rejected` outcome `responses` SHALL be nil, because upstream writes no
  `response` key on that path.
- **P1b. The answers passed to the claim SHALL be the N3a-normalized ones, not the caller's raw
  input.** `metadata.response` is what R2b replays to a losing caller, so normalizing after the claim
  — or not at all — would make N3a's byte-identity guarantee hold for the winner's own response and
  break for every replay of it. Normalization is therefore applied between step 3 and step 4.
- **P2. `ResolveBundle` SHALL NOT re-derive activeness.** Whether a bundle is claimable is decided
  **only** by upstream's predicate, inside its transaction. A pre-check in `ResolveBundle` would be
  a TOCTOU window and could disagree with the authoritative predicate; steps 1–3 exist to
  authorize and validate, never to pre-judge the claim.

## Determinism and boundary rules

- **D1. A bundle's `created_at` is the minimum `created_at` across its `clarification_request`
  messages.** The bundle's messages are written in a loop and therefore carry distinct timestamps;
  without this rule L6's ordering is not well defined.
- **D2. Questions within a bundle are ordered by `question_index` ascending, then message
  `created_at` ascending, then message `id` ascending.** The two extra keys are not decoration:
  `questionIndexFromMetadata` returns **0** for a missing or unparseable `question_index`, so a
  legacy or corrupt bundle can present several questions all claiming index 0. Message `id` is a
  primary key, so the composite is total.
- **D3. `metadata.status` on a `clarification_request` message is one of `pending`, `answered`,
  `rejected`, `cancelled`, or `expired`** — the `clarification.Status` constants — or **absent**.
  For membership this spec defers entirely to D4; it does **not** define its own effective-pending
  rule. The distinction matters at one boundary and is stated so it is not invented: upstream's
  predicate is `COALESCE(status,'') IN ('','pending')`, so an **absent** status counts as pending
  but an **unrecognized** one does not. The first version of this spec required the opposite for
  unrecognized values (fail closed). That requirement is withdrawn — see *Retired criteria* G5 —
  because two consumers disagreeing about membership is the defect, and upstream's rule is the one
  the workflow guard, the chat overlay, and the claim all already share.
- **D4. A bundle is *pending* — listable by L1, claimable by step 4, and countable by the workflow
  guard — iff it is ACTIVE per upstream's rule.** There is one membership test in the system and it
  is not this spec's. Concretely, and only as a restatement of the upstream predicate a builder will
  read directly: at least one of the bundle's `clarification_request` messages has
  `COALESCE(metadata.status,'') IN ('','pending')`, **and** the bundle's `turn_id` is the session's
  current turn per `turnAuthorityPredicate`, **and** the session's state is not `completed`,
  `failed`, or `cancelled`.
- **D4a. Legacy bundles fall out of D4 with no backfill and no migration.** Every clarification
  answered before either change is a set of messages carrying a terminal `status`, so the first
  conjunct excludes it; every clarification stranded on an older turn is excluded by the second.
  Nothing this spec adds needs to run against historical data, which is what makes "no migration"
  safe rather than merely cheap.
- **D5. A task with an empty `workspace_id` is visible to every authenticated caller**, matching
  `authorizeTaskID`. Its bundles appear in L1 for everyone. This preserves the pre-auth-row behavior
  used everywhere else in the codebase.
- **D6. Pagination is not a snapshot.** A bundle that becomes inactive between two pages simply
  disappears; because the cursor is a `(created_at, pending_id)` key rather than an offset, no other
  bundle shifts position or is skipped. A bundle created with a `created_at` earlier than an
  already-issued cursor (only reachable via clock adjustment) SHALL NOT be returned to that cursor's
  holder; it is returned on any fresh, cursor-less call.
- **D7. `age_seconds` uses the server clock and is floored at 0**, so a bundle whose stored
  `created_at` is in the future reports `0` rather than a negative number.

## What

Each criterion below is observable through the HTTP API, the MCP tool surface, or the database.

### Resolution semantics (applies to every answering surface)

- **R1.** When a caller submits a resolution for an **active** bundle and
  `CompleteActiveClarificationBundle` returns `claimed == true`, that caller SHALL be treated as the
  winner and SHALL be the only caller that performs step 5.
- **R2. A losing caller SHALL be told what the winner decided, not merely that it lost.** When the
  claim returns `claimed == false`, the system SHALL re-read the bundle's `clarification_request`
  messages and branch on their durable status:
  - **At least one message carries `answered` or `rejected`** — a winner exists. The system SHALL
    return a **success** response carrying `claimed: false` plus the winner's `status` and
    reconstructed `response` (R2b), SHALL NOT modify any message, and SHALL NOT publish any event.
  - **No message carries `answered` or `rejected`** — there is no winner; the bundle simply is not
    active (superseded turn, terminal session, `expired`, `cancelled`, or malformed). The system
    SHALL return **409** with upstream's existing message, unchanged.
  This branch is the load-bearing addition, because `CompleteActiveClarificationBundle` returns the
  same `claimed == false` for both states and a caller cannot distinguish them. Collapsing them —
  in either direction — produces a concrete lie: reporting 409 for a duplicate answer hides the
  winner's payload, which is the whole point of idempotent replay; reporting "success, here is the
  winner's answer" for a superseded bundle invents a winner that does not exist and would have the
  MCP tool tell an agent its answer was superseded by an answer nobody gave.
- **R2a. The re-read is not required to agree with the failed claim, and SHALL NOT be retried.** The
  bundle can change again between the claim and the re-read. Whatever the re-read observes is what
  the caller is told; a single read is the contract. Retrying to obtain a "more settled" answer would
  race the same transitions indefinitely, and every outcome of the re-read is already a truthful
  statement about a real moment.
- **R2b. Reconstructing the winner's `response`.** `status` is the status of the **first message in
  D2 order** whose status is `answered` or `rejected`; a bundle claimed by upstream is uniform, so
  this tiebreak only ever binds on a legacy mixed bundle, where it is still total and reproducible.
  `answers` is built by walking the bundle's messages in D2 order and taking each message's
  `metadata.response` where present, in that order; a message without one contributes no entry, so a
  rejection yields `[]`. `rejected` is `true` when `status` is `rejected`.
  **`reject_reason` SHALL be the empty string on every replay.** Upstream stores no reject reason on
  the message rows — `completeClaimedClarificationMessages` writes only `status`,
  `response_delivery_pending` and, for `answered`, `response` — so there is nowhere to read it from.
  This is stated rather than repaired: repairing it means adding a metadata key to a shape the
  *Upstream baseline* freezes, which belongs to the active-lifecycle card, not this one. A loser
  therefore learns *that* the bundle was declined and *by what outcome*, but not the declining
  caller's prose.
- **R2c. Validation runs before the loser branch.** A malformed submission against an
  already-resolved bundle SHALL receive the same validation error it would receive against an active
  one, and SHALL NOT receive the winner's payload. Returning success for a request the system could
  not parse would tell a caller its malformed answer had been accepted. This follows from N8c
  ordering validation ahead of step 4, and is restated here because R2 is where it is observable.
- **R3.** While two callers submit resolutions for the same `pending_id` concurrently, exactly one
  SHALL observe `claimed == true` and the other SHALL observe R2's winner branch. This SHALL hold
  when the two callers are served by different HTTP requests, and — the case no existing test can
  cover, because the MCP tool did not exist when upstream's tests were written — **when one is the
  web UI over REST and the other is `answer_question_kandev` over MCP**.
- **R4.** The durable claim SHALL complete before any resume event is published, so a loser can
  never trigger a resume. This holds by construction once P1 is satisfied: the claim is a committed
  transaction and step 5 runs only for the winner.
- **R4a. When `CompleteActiveClarificationBundle` returns an error rather than a `claimed` boolean**,
  the system SHALL return **500**, SHALL NOT retry, and SHALL log the `pending_id` and the error.
  Reachable causes are upstream's own: a database failure, a claimed/loaded row-count mismatch, and
  a claimed message with an empty `question_id`. The last is why L16 bundles are excluded from L1
  and are not answerable at all (L16); it is not a caller error and SHALL NOT be reported as 400.
- **R6.** When the backend restarts between a bundle's creation and its resolution, a subsequent
  resolution SHALL still be claimed exactly once, and SHALL succeed whenever the bundle is still
  active. The claim SHALL NOT depend on in-memory state. A plain restart does not by itself end a
  turn or terminate a session, so a bundle stranded by one remains active and answerable; a bundle
  whose session has since accepted a newer turn does not, per D4.
- **R7. The winner's delivery and resume path is upstream's, reached unchanged.** The system SHALL
  call the existing `Store.RespondWithDeliveryConfirmation` path and SHALL NOT re-implement live
  delivery, detached resume dispatch, or the `RestoreActiveClarificationBundle` rollback. A live
  waiter therefore receives the response in the same turn; a detached current-turn bundle resumes
  through upstream's bounded-wait dispatch; a dispatch that cannot be accepted rolls the claim back
  and the bundle becomes answerable again.
- **R7a. HTTP 200 on a winning resolution therefore means more than "recorded".** It means the claim
  committed **and** the response either reached a live waiter or had one resume dispatch accepted.
  A failure of either yields a 5xx from upstream's existing handling, with the bundle rolled back.
  This is a stronger guarantee than the four-valued `resume` field the first version of this spec
  specified, which is why that field is retired rather than reproduced (see *Retired criteria* R8a):
  there is no longer a success case in which the caller must be told the resume is in doubt.
- **R9. A rejection SHALL produce the same agent-visible outcome as a human skip.** It is claimed
  with `status = rejected`, and upstream's delivery path decides what the agent sees: a live waiter
  receives a `clarification.Response` with `rejected: true` and the caller's reason; a detached
  current-turn bundle is persisted rejected without resuming the agent. The wire format does not
  distinguish the answerer — a reject from an external agent means the same thing to the blocked
  agent as a human skip.

### REST status codes and response envelope

- **R10.** `POST /api/v1/clarification/:id/respond` SHALL use exactly these outcomes. This table is
  the contract W2/W3 and the E2E duplicate-submit case are written against.

| Outcome | Status | Body |
|---|---|---|
| won the claim (R1) | 200 | `{"success": true, "claimed": true, "status": "...", "response": {...}}` |
| lost to a resolved winner (R2 winner branch) | 200 | same shape, `"claimed": false`, winner's `status`/`response` |
| not active, no winner (R2 no-winner branch) | 409 | `{"error": "clarification request is no longer active"}` |
| validation failure (N6–N8b) | 400 | `{"error": "<message naming the offending field>"}` |
| unknown / unauthorized `pending_id` | 404 | `{"error": "clarification request not found"}` |
| claim error (R4a) or delivery failure (R7) | 500 | `{"error": "<message>"}` |

- **R11. The `success` key SHALL be retained** on `POST` responses so an existing client that only
  checks `res.ok` and `success` keeps working. `claimed`, `status`, and `response` are additive.
  **The 409 is narrowed, not removed.** Upstream returns 409 for every `claimed == false`; after
  this change 409 means *only* "not active and no winner", and the duplicate-answer case that used
  to share it becomes a 200 with `claimed: false`. Clients that already treat 409 as a successful
  submit (W2) keep working in both cases because they also treat 200 as success.
- **R12. `response` SHALL always emit `answers`, `rejected` and `reject_reason`, and each entry's
  `question_id`, `selected_options` and `custom_text`**, using `[]` for an empty array and `""` for
  an empty string. `clarification.Response` declares `omitempty` on `Answers`, `Rejected`,
  `RejectReason` and `Answer.SelectedOptions`/`CustomText`, so marshalling the struct as it stands
  omits the **key entirely** for an empty slice, a `false` bool or an empty string — a rejection's
  payload would carry no `answers` key at all and a client reading `response.answers` would get
  `undefined`. The struct tags **SHALL NOT be changed**: they are the wire shape of
  `ask_user_question_kandev`'s own tool result, which *Out of scope* freezes. An explicit
  serialization for this envelope is therefore required, and it binds the REST body and the MCP
  result alike.

### Authorization

This is the deliverable upstream did not build. Every criterion here is unchanged in intent from the
first version of this spec; only the endpoint set's behavior around the claim has moved.

- **A1.** `POST /api/v1/clarification/:id/respond` SHALL deny a request whose caller cannot access
  the task owning that `pending_id`.
- **A2.** `GET /api/v1/clarification/:id`, `GET /api/v1/clarification/:id/wait`, and
  `POST /api/v1/clarification/:id/cancel` SHALL apply the same check.
- **A3.** A denial under A1/A2 SHALL be a **404** with a body indistinguishable from a nonexistent
  `pending_id`. It SHALL NOT be a 403 and SHALL NOT include the question text, option labels, task
  ID, session ID, or workspace ID.
- **A4.** An unscoped caller SHALL be authorized for every `pending_id`. Concretely: **with auth
  disabled, no caller is ever newly denied**, and any behavior this spec does not deliberately
  change is unchanged. The deliberate changes below apply in **both** auth modes — there is one code
  path, not an auth-disabled variant:
  1. a duplicate submission against a bundle that already has a winner returns 200 with
     `claimed: false` and the winner's payload, instead of 409 (R2, R11);
  2. every successful response gains `claimed`, `status`, and `response` fields (R10, R12);
  3. a `pending_id` with no durable messages returns 404 (A5);
  4. the new validation rules reject submissions that pass today: unknown option IDs (N8),
     `rejected: true` combined with answers (N8a), and `reason`/`custom_text` over 2000 runes (N8b);
  5. an answers submission against a bundle whose messages carry no `question_id` is rejected before
     the claim (L16) instead of reaching upstream's claim and failing there with a 500;
  6. `GET /:id/wait` on a `pending_id` with **no durable messages** returns **404** instead of
     today's **504** (A5a).
  This list is exhaustive. A behavior not named here SHALL be identical to the pre-change behavior
  for an unscoped caller on all four endpoints. In particular, 409 for a genuinely inactive bundle
  is **not** on this list: it is preserved exactly as upstream returns it today.
- **A5.** A `pending_id` whose durable messages cannot be found SHALL produce the same 404 as A3.
  This also covers the M5a case where a bundle's `task_id` cannot be resolved from either source,
  for a scoped caller.
- **A5a. A5 binds all four endpoints, in both auth modes — including `GET /:id/wait`, which returns
  504 for that input today.** A8 resolves the authorizing `task_id` from the durable messages on all
  four endpoints and A7 puts that resolution ahead of the in-memory read, so a `pending_id` with no
  durable messages fails at step 1 on every endpoint, for an unscoped caller as much as a scoped one.
  It is enumerated rather than avoided because the alternative breaks a security property. Exempting
  the two read endpoints from A5 would leave `GET /:id/wait` returning 404 for a **foreign** bundle
  (A3) and 504 for a **nonexistent** one — a status-code oracle telling an unauthorized caller
  exactly which `pending_id`s exist, which is the precise distinction A3 exists to prevent. A
  compatibility promise can be amended by adding a line to A4; an existence-disclosure channel
  cannot be amended at all. The 504 is preserved where it means something: an authorized caller
  waiting on a bundle that **does** exist.
- **A6.** `POST /api/v1/clarification/request` (creation) SHALL be unchanged by this spec. It is
  called by the in-session agent path, which carries the task owner's identity via `internal/mcp/scope`.
- **A7.** The A2 authorization check SHALL run **before** the in-memory read on both read endpoints,
  so an unauthorized caller receives A3's 404 on either and can never distinguish a foreign bundle
  from a nonexistent one by status code. An **authorized** caller's post-authorization behavior is
  unchanged **for a bundle whose durable messages exist**: 404 from `GET /:id` when the in-memory
  entry is gone, 504 from `GET /:id/wait` on drain or timeout.
- **A8.** On all four endpoints the authorizing `task_id` comes from the durable messages via M5,
  never from the in-memory `Request.TaskID`. A7's ordering requires it — the check runs before the
  in-memory read, so the in-memory value is not yet available — and it also removes a discrepancy:
  the in-memory `Request.TaskID` is populated from the same possibly-empty session lookup as the
  message column, so trusting it would reintroduce the M5 hole on two endpoints while the other two
  resolved it correctly.

- **A9. Cancel is authorized without being claimed.** `POST /:id/cancel` does **not** go through
  `ResolveBundle` — X1's routing is retired — so A2's check SHALL be applied by running
  `ResolveBundle` steps 1 and 2 alone (resolve the bundle's `task_id` per M5, then
  `AuthorizeTaskAccess`) ahead of the handler's existing body, and returning A3's 404 on either
  failure. Everything after that check is today's cancel, unchanged: it still requires a live
  in-memory entry, still returns 404 without one, and still applies its per-question updates in a
  log-and-continue loop. Stating this is what stops a builder inferring from A2 that cancel must be
  re-routed through the claim, which P1 and upstream's answered/rejected-only terminal domain forbid.

**BREAKING CHANGE, intentional.** An authenticated caller that today answers any bundle by bare
`pending_id` will receive 404 for bundles outside its workspaces. The only in-tree production caller
is the web UI, which answers from a task it can already read, so it is unaffected — subject to W1
below. The six auth-mode-independent changes enumerated in A4 are also intentional and accepted.

### Web client

- **W1.** The web UI's clarification POSTs (`apps/web/hooks/domains/session/use-clarification-group.ts`,
  both call sites) SHALL send credentials. They currently use a bare `fetch` with the default
  `credentials: "same-origin"`, unlike the shared client (`lib/api/client.ts`, `credentials: "include"`).
  In split-origin dev mode (`__KANDEV_API_PORT` set, browser and API on different ports) the session
  cookie is therefore dropped, so with auth enabled the request is already rejected by the global
  middleware before this spec's changes. Authorization becomes load-bearing on this route, so the
  omission is fixed here.
- **W2.** The web UI SHALL treat a `claimed: false` success as a successful submit and close the
  overlay, the same way it already treats a 409. Both outcomes remain "someone else settled this";
  the client's existing 409 handling SHALL be retained unchanged, because R11 keeps 409 reachable
  for a genuinely inactive bundle.
- **W3.** On a `claimed: false` **200** the web UI SHALL apply the **winner's** returned `response`
  to the bundle's local message metadata, not the answers this client submitted.
  `postClarificationBatch` and `postClarificationSkip` currently inspect only `res.ok` / `res.status`,
  never the body, and `safeApplyResolvedStatus` then optimistically writes **this client's** answers
  into `metadata.response`. Because R2 guarantees the losing submit produces no
  `session.message.updated` broadcast, nothing would ever correct that write: the losing tab would
  display the losing answers as the transcript until a reload. Both call sites SHALL parse the
  response body and pass the winner's answers to the optimistic update. When `claimed` is absent from
  the body (an older backend, or the 409 path), the client SHALL keep today's behavior.
- **W3a. The winner's `status` domain is `answered` or `rejected`.** `safeApplyResolvedStatus` and
  `applyResolvedStatusToBundle` already accept exactly `"answered" | "rejected"`, which now matches
  the backend's terminal domain exactly, so **no union widening is required.** This is stated
  because the first version of this spec required adding `"cancelled"` to that union; upstream's
  claim cannot produce a cancelled winner (its terminal domain is answered/rejected only), so a
  cancelled bundle now reaches the client as the 409 no-winner branch instead. See *Retired
  criteria* W3a.
- **W4.** The overlay's free-text input (`clarification-input-overlay.tsx`, which enforces no limit
  today) SHALL stop a human at the same boundary N8b enforces on the server, so a long answer is
  caught at the input rather than returning an opaque 400 on submit.
- **W4a. The client-side guard SHALL count runes, and the HTML `maxLength` attribute alone SHALL NOT
  be the mechanism.** N8b's cap is 2000 UTF-8 **runes**, chosen explicitly so a non-Latin answer is
  not cut short. The `maxLength` attribute counts **UTF-16 code units**, so every astral character —
  emoji, and much CJK Extension B — consumes two of its budget. `maxLength={2000}` would stop a user
  at 1000 emoji the server would have accepted: not the opaque-400 failure W4 exists to prevent, but
  the mirror-image one, a client refusing input the contract permits, with no error message at all
  because `maxLength` fails silently. The overlay SHALL enforce the limit by counting runes (code
  points) on the input's value and SHALL surface the boundary to the user rather than silently
  truncating. `maxLength` MAY be set in addition, as a coarse backstop, only at a value that cannot
  reject anything the server accepts — **no lower than 4000**, since a rune is at most two UTF-16
  code units. It SHALL NOT be set to 2000. Boundary values follow N8b exactly: 2000 runes is
  accepted, 2001 is not, and the count is over code points, not bytes and not UTF-16 units.

### `list_pending_questions_kandev` (external MCP surface only)

- **L1.** The tool SHALL return every **active** bundle (D4) in the workspaces visible to the caller,
  and no bundle outside them.
- **L1a.** Visibility SHALL be resolved by the same rule as `filterWorkspacesForCaller`
  (`task/service/service_access.go`): an unscoped caller sees every workspace; a scoped caller sees a
  workspace whose `owner_id` is empty or matches the caller. The tool SHALL resolve that
  workspace-ID set first and apply it as a **predicate of the bundle query**, not as a post-query
  filter over an already-limited page. Per-bundle `AuthorizeTaskAccess` calls are NOT the mechanism:
  N calls per page would be N round trips, and — decisively — filtering after `LIMIT` would make
  L10's `limit` mean "rows examined" rather than "bundles returned", so a page could come back short
  or empty while more matching bundles exist, and a cursor-polling caller could not distinguish that
  from exhaustion. `limit` counts **returned** bundles.
- **L1b.** When the resolved workspace-ID set is empty — a scoped caller who owns no workspaces and
  can see no unowned ones — the tool SHALL omit the `workspace_id IN (...)` **term** from the L1c
  disjunction rather than issuing it, because an empty `IN ()` is a syntax error on both dialects.
  It SHALL NOT short-circuit the whole query, and there is **no** whole-query short-circuit branch in
  this tool. L1c's other disjuncts are predicates on the task row rather than on the caller, so they
  remain applicable no matter what the caller can see: a scoped caller with no visible workspaces can
  still legitimately be shown bundles whose task has an empty `workspace_id` or a dangling workspace
  reference, exactly as `authorizeTaskID` would allow them to answer those bundles.
- **L1c. The visibility predicate SHALL reproduce `authorizeTaskAccess`, not a narrower
  workspace-membership test.** The list tool and the answer tool MUST agree on visibility: a bundle
  `answer_question_kandev` will answer and `list_pending_questions_kandev` will not show is a silent
  discovery hole, and discovery is what this card exists to add. `AuthorizeTaskAccess` delegates to
  `authorizeTaskID`, which permits a scoped caller in **two** cases a bare
  `workspace_id IN (visible set)` term cannot express. The predicate is therefore a three-way
  disjunction, evaluated over the **M5-resolved** task:
  1. **The task's `workspace_id` is empty.** `authorizeTaskID` returns nil early on
     `task.WorkspaceID == ""`. This is D5's case, and D5 already states such bundles appear in L1
     for everyone — the predicate must actually deliver that.
  2. **The task's `workspace_id` names no existing workspace row.** `authorizeTaskID` treats a failed
     workspace lookup as visible, by an explicit `//nolint:nilerr` fallback whose comment reads "a
     dangling workspace reference should not hide the task from the single user who can already see
     everything else about it". `filterWorkspacesForCaller` cannot express this because it filters a
     list of workspaces that *exist*.
  3. **The task's `workspace_id` is in the L1a visible set.** This is the ordinary case, and it is
     the disjunct the `IN` term expresses.
  For an unscoped caller the predicate is satisfied unconditionally, matching `callerScope` returning
  `ok=false`.
- **L1d. Mechanism for L1c, so it is not invented.** Disjunct 1 is a comparison against the literal
  empty string, because `tasks.workspace_id` is `TEXT NOT NULL DEFAULT ''` with no foreign key —
  empty is its default, not an anomaly. Disjunct 2 is an absence test against the `workspaces` table
  (`NOT EXISTS (SELECT 1 FROM workspaces w WHERE w.id = t.workspace_id)`, or the equivalent left join
  with a null check); it is a plain relational predicate and needs **no** `internal/db/dialect`
  helper. Disjunct 3 is the workspace-ID set from L1a, subject to L1b's empty-set handling. The three
  are combined with `OR` and the whole disjunction is `AND`-ed with D4's activeness test, all inside
  the single bundle query — per L1a visibility is a query predicate, never a post-`LIMIT` filter.
  **Separately from the disjunction**, the join reaches the task through **M5's rule** —
  `task_session_messages.task_id` when non-empty, otherwise the bundle's session row's `task_id` —
  because the obvious `JOIN tasks ON tasks.id = messages.task_id` silently drops every legacy
  empty-`task_id` bundle for **every** caller, unscoped included. That is a join-path rule, not a
  fourth disjunct, and it decides which task row disjuncts 1–3 evaluate against.
- **L2. The tool SHALL derive its result from the durable `clarification_request` messages**, NOT
  from `Store.ListPending`, and SHALL therefore return the correct set after a backend restart.
  `Store.ListPending` returns nothing after a restart because the map is empty. The membership test
  is **D4**, applied as predicates of the bundle query.
- **L2a. The list query SHALL reuse upstream's activeness expression rather than restate it.** D4 is
  upstream's rule, and the list tool is the third consumer of it after the workflow guard and the
  claim. The current-turn and non-terminal-session predicates SHALL be built from the same helpers
  those two already use (`turnAuthorityPredicate`, the non-terminal-session predicate) rather than
  hand-written, so a future change to activeness cannot leave this tool behind. This is the concrete
  form of upstream's own requirement that *"all backend consumers derive active clarification state
  from one repository rule"*.
- **L3.** Each returned bundle SHALL carry: `pending_id`, `task_id`, `session_id`, `created_at`
  (RFC3339 UTC), `age_seconds` (integer, server clock minus `created_at`, floored at 0), `context`,
  and `questions`.
- **L4.** Each question SHALL carry `question_id`, `title`, `prompt`, `status`, and `options`, where
  each option carries `option_id`, `label`, and `description` — the exact identifiers
  `answer_question_kandev` accepts.
- **L4a. Every field named in L3 and L4 is always present and is never JSON `null`.** When a value is
  unknown, absent, or unparseable:
  - a **string** field (`task_id`, `session_id`, `context`, `question_id`, `title`, `prompt`,
    `option_id`, `label`, `description`) SHALL be emitted as the **empty string** `""`;
  - an **array** field (`questions`, `options`) SHALL be emitted as an **empty array** `[]`;
  - `age_seconds` SHALL be emitted as an integer, floored at 0 per D7, never null;
  - `created_at` and `status` have no unknown case: `created_at` is D1's `MIN(created_at)` over rows
    that exist by construction, and a message whose `status` key is absent is reported as the string
    `pending`, matching the `COALESCE(status,'') IN ('','pending')` that admitted it.
  Without this rule a builder emitting Go zero values through one path and `null` through another
  produces a shape that changes between bundles, and an MCP client iterating `options` or reading
  `label` on a degraded bundle would meet `null` where the contract implied an array or a string.
- **L5.** Questions within a bundle SHALL be ordered by D2's total key.
- **L6.** Bundles SHALL be ordered by `created_at` ascending, then by `pending_id` ascending. The
  `pending_id` tiebreak exists solely to make the order total for cursor pagination; it carries no
  meaning. Oldest-first is the useful order because the oldest blocked agent is the most urgent.
- **L7.** The tool SHALL accept an optional `workspace_id`. When supplied, results SHALL be limited
  to bundles whose task — resolved per M5 — carries exactly that `workspace_id`, and a workspace the
  caller cannot access SHALL produce the same empty-result response as an empty workspace (no
  existence leak, consistent with A3).
- **L7a. How `workspace_id` composes with L1c, and what the empty string means.**
  1. **`workspace_id` is one additional predicate `AND`-ed with the whole L1c disjunction** — never a
     substitute for it, and never a fourth disjunct. Adding an `AND` term can only ever NARROW the
     result, so supplying `workspace_id` can never reveal a bundle an unfiltered call would withhold.
  2. L7's empty-result guarantee for an inaccessible workspace **falls out of that `AND`** and needs
     no short-circuit branch. For a workspace that exists and the caller cannot see: disjunct 1 is
     false (the task's `workspace_id` is non-empty), disjunct 2 is false (the workspace row exists),
     and disjunct 3 is false (it is not in the L1a set). L1b's "there is no whole-query short-circuit
     in this tool" therefore holds without exception.
  3. A **fabricated or deleted** `workspace_id` leaves disjunct 2 satisfiable, so bundles whose task
     carries that dangling reference ARE returned. That is correct rather than a leak: they are
     exactly the bundles `authorizeTaskID`'s dangling-workspace fallback already lets this caller
     answer, and an unfiltered L1 call would have listed them anyway. Nothing is disclosed about a
     workspace that does not exist.
  4. **`workspace_id: ""` means the parameter was not supplied.** It SHALL NOT be read as "filter to
     tasks whose `workspace_id` is empty", even though disjunct 1 and D5 make that a real class. An
     omitted optional string decodes to `""`, so the other reading would silently narrow every caller
     who omits the argument down to the empty-workspace class alone. Those bundles are reached by
     making an **unfiltered** call. This spec deliberately provides no filter selecting them
     exclusively; that is a named exclusion, not an oversight.
- **L8.** The tool SHALL accept an optional `created_since` (RFC3339). When supplied, only bundles
  with `created_at >= created_since` SHALL be returned. The parameter is named for the column it
  filters: a bundle's `created_at` never changes, so an `updated_since` name would promise
  change-feed semantics this tool does not have.
- **L9.** The tool SHALL accept an optional `cursor` — the opaque encoding of the last returned
  `(created_at, pending_id)` pair — and SHALL return only bundles ordered strictly after it under L6.
  It SHALL return a `next_cursor` when more results exist and an empty `next_cursor` when they do not.
- **L10.** The tool SHALL accept an optional `limit`, defaulting to **50** and capped at **200**. A
  `limit` below 1, or absent, SHALL be treated as the default; a `limit` above the cap SHALL be
  clamped to the cap rather than rejected. Per L1a, `limit` counts bundles actually returned.
- **L11.** The response envelope SHALL be
  `{"bundles": [...], "count": <int>, "next_cursor": "<string>"}`. `bundles` is the top-level array —
  each element carries its own `questions` array per L3, so the two names never collide. `count` is
  the number of elements in `bundles` on **this page** and is always equal to `len(bundles)`; it is a
  convenience, not a total. When no bundle matches, the tool SHALL return an empty `bundles` array,
  `count: 0`, and an empty `next_cursor`, and SHALL NOT return an error.
- **L11a.** A grand total across all pages is deliberately NOT provided. Producing one would require
  a second, unbounded, authorization-filtered aggregate query per call, and it would be stale the
  moment it was computed (D6). Callers that need to know whether more work exists read `next_cursor`.
- **L12. A bundle whose per-question messages disagree on `status` (some pending, some terminal) is
  returned iff it satisfies D4** — that is, iff at least one message is still pending and the bundle
  is on the current turn of a non-terminal session. Each question SHALL carry its own `status`. Such
  a bundle is a legacy artifact: upstream's claim writes every row in one transaction, so nothing
  produced after this change can be mixed. Returning it lets a caller finish it; the claim will then
  transition only the still-pending rows, which is exactly upstream's predicate.
- **L13.** An unparseable `created_since` or an unparseable/corrupt `cursor` SHALL produce a
  validation error naming the offending argument. Neither SHALL be silently ignored: a caller polling
  with a cursor it thinks is being honored, that is in fact being dropped, re-reads the whole backlog
  every tick and re-answers questions it already handled.
- **L14.** Supplying both `cursor` and `created_since` SHALL be accepted; both constraints apply
  (intersection). `cursor` is the pagination position, `created_since` is a filter, and they are
  independent.
- **L15.** A bundle whose durable messages carry no parseable `question` metadata SHALL still be
  returned when it satisfies D4 and L16, with the affected question carrying its `question_id` and,
  per L4a, an empty `title`, `prompt` and `options` rather than null ones. Such a question cannot be
  answered by option ID — every `selected_options` entry would fail N8 against an empty option list —
  but hiding the bundle would strand its agent invisibly, so it remains answerable by `custom_text`
  alone (N7) or by rejection.
- **L16. A bundle in which ANY message carries an empty or absent `question_id` SHALL be excluded
  from L1, and SHALL be rejected by `answer_question_kandev` and the REST endpoint before the claim.**
  Upstream's `completeClaimedClarificationMessages` returns
  `clarification message %s is missing question_id` and aborts its transaction, so such a bundle
  cannot be resolved by any outcome — not by an answer, and not by a rejection. Listing a bundle no
  caller can act on is a discovery lie: the tool would advertise a blocked agent and every attempt to
  clear it would return 500. Excluding it is therefore the honest contract, and it is the whole
  bundle that is excluded, not the offending message, because the claim aborts on the first one it
  meets. The pre-claim rejection SHALL name the condition rather than surfacing upstream's 500 (R4a).
  A human still sees the bundle in the chat transcript, and it is still reachable through
  `get_task_conversation_kandev`. Making such a bundle resolvable requires a change to upstream's
  claim and is named in *Out of scope*.

### `answer_question_kandev` (external MCP surface only)

- **N1.** The tool SHALL accept `pending_id` plus either `answers` (one entry per question) or
  `rejected: true` with an optional `reason`.
- **N2.** The tool SHALL resolve the bundle through the same `ResolveBundle` operation as the REST
  endpoint, and SHALL therefore inherit R1–R9 and A1–A5 without a second code path.
- **N3.** On winning, the tool SHALL return `claimed: true` with the recorded `status` and the
  normalized `response` (N3a).
- **N3a. Normalization** is the canonical form of the answer payload. It is defined so that two
  callers submitting semantically identical answers produce byte-identical **answer payloads** — the
  `answers`, `rejected` and `reject_reason` fields. Rules:
  1. `answers` entries are ordered by the bundle's own question order (L5), **not** by the order the
     caller supplied them.
  2. Within an entry, `selected_options` is ordered by the option's position in the question's
     `options` array, and exact duplicates are removed.
  3. `custom_text` and `reason` are stored verbatim after trimming leading and trailing whitespace.
     No other transformation is applied. Trimming happens **after** N8b's length validation, which
     runs on the caller's raw input at step 3, so a value one rune over the cap is rejected even when
     trimming would have brought it under.
  4. An absent `answers`, `selected_options`, or `options` array is emitted as an empty JSON array
     `[]`, never `null` and never as an **omitted key**. **R12 states the mechanism** and is not
     optional here: the guarantee is unreachable through `encoding/json` on `clarification.Response`
     as tagged.
- **N4.** On losing to a resolved winner, the tool SHALL return `claimed: false` with the winner's
  `status` and reconstructed `response` (R2b), and SHALL NOT report an error. Answering an
  already-answered question is a successful no-op that tells the caller what the answer was.
- **N4a. On losing to an inactive bundle with no winner (R2's second branch), the tool SHALL report
  an error** naming the bundle as no longer active, distinct from both success and not-found. A
  caller must be able to tell "you were beaten, here is the answer" from "this question is no longer
  answerable and nobody answered it", because the two imply different next actions: the first is
  done, the second may need a human.
- **N5.** A `pending_id` the caller cannot access SHALL produce the same not-found error text as a
  nonexistent one.
- **N6.** An `answers` array SHALL be rejected with a validation error, and SHALL NOT reach the
  claim, when **any** of these four conditions holds. The list is exhaustive:
  1. It does not contain exactly one entry per question in the bundle.
  2. An entry carries an **empty** `question_id`.
  3. An entry references a `question_id` not in the bundle's expected set.
  4. An entry repeats a `question_id` already used by an earlier entry.
  All four are the existing rule in `validateRespondAnswers`.
- **N6a.** The expected question-id set SHALL be derived from the bundle's durable messages, counting
  **one expected answer per `clarification_request` message** in the bundle. Today
  `validateRespondAnswers` falls back to permissive acceptance when it cannot determine that set;
  under this spec step 1 has already proven the messages exist and L16 has already excluded every
  bundle whose ids are empty, so the expected set is always non-empty and that permissive branch
  SHALL NOT be reachable from `ResolveBundle`.
- **N7.** An answer entry MAY carry `selected_options` (option IDs), `custom_text`, or both. An entry
  carrying neither SHALL be accepted and SHALL render as "(no answer)" in the resume prompt,
  preserving `formatAnswerBody`.
- **N8.** A `selected_options` entry naming an `option_id` not present on that question SHALL be
  rejected with a validation error and SHALL NOT reach the claim. *(This is stricter than today's
  REST endpoint, which does not check option IDs. External agents fabricate identifiers; the human at
  the keyboard clicks a rendered button. The check is applied on both surfaces so the two cannot
  drift.)* N8 constrains **membership only**. It does not constrain cardinality: `selected_options` is
  a slice and nothing in the existing model marks a question single- or multi-select, so an entry
  naming several valid option IDs SHALL be accepted. Inventing a single-select rule here would reject
  answers the overlay itself can produce.
- **N8a.** A request carrying both `rejected: true` and a non-empty `answers` array SHALL be rejected
  with a validation error and SHALL NOT reach the claim. The two are mutually exclusive outcomes and
  guessing which the caller meant would silently discard one of them. A request carrying
  `rejected: false` with an empty `answers` array is the N6 count-mismatch case and is likewise
  rejected, **including for a single-question bundle**: N7 governs an answer *entry* that carries
  neither field, and an empty array contains no entry at all. A caller that means "no answer" for a
  one-question bundle sends one entry with neither field (N7); a caller that means "I decline" sends
  `rejected: true`.
- **N8b.** `reason` SHALL be capped at **2000 runes**; a longer value SHALL be rejected with a
  validation error rather than truncated, since the reason is replayed verbatim into the blocked
  agent's resume prompt. `custom_text` on an answer SHALL be capped at the same limit, per entry. The
  cap is enforced inside `ResolveBundle`, so it binds the REST endpoint and the web overlay as well
  as this tool (W4a adds the matching client-side guard). The limit counts UTF-8 **runes**, not
  bytes, so a non-Latin answer is not cut short at a third of the visible length.
- **N8c.** Validation (N6, N6a, N7, N8, N8a, N8b, L16) SHALL run **before** the claim in step 4, so a
  malformed request never resolves a bundle, and before R2's loser branch (R2c). A validation error
  SHALL leave the bundle untouched.
- **N8d. Validation order among the rules is unspecified and deliberately so.** When one submission
  violates several, any one of them MAY be reported; R10 requires only a 400 whose message names the
  offending field. Pinning an order would constrain the error string without changing any state
  outcome — every ordering rejects the same set of submissions, writes nothing, and leaves the bundle
  answerable. A test SHALL therefore assert the 400 and the named field for each rule in isolation,
  never a particular winner among simultaneous violations.
- **N9. Argument schema.** Both tools SHALL declare their arguments using the same
  `mcp.NewTool` / `mcp.WithString` / `mcp.WithBoolean` / `mcp.WithNumber` / `mcp.WithArray` /
  `mcp.WithObject` helpers every other tool on this surface uses, with `mcp.Required()` on
  `pending_id` and on nothing else. `answers` is an array of objects whose shape mirrors
  `ask_user_question_kandev`'s own nested `questions[].options[]` declaration, which is the in-repo
  precedent for an array-of-objects argument. A raw JSON Schema via `NewToolWithRawSchema` is
  permitted where the helpers cannot express the nesting. No new schema convention is introduced.

### Surface placement

- **S1.** Both tools SHALL be registered for `SurfaceExternal` only.
- **S2.** Neither tool SHALL appear on `SurfaceKanbanTask`, `SurfaceOfficeTask`, or
  `SurfaceConfiguration`. In-session MCP scoping resolves to the workspace **owner**
  (`internal/mcp/scope`), not to a task relationship, so a running agent on the kanban surface would
  be able to list and answer human questions across every task that owner can see. That defeats the
  human-input boundary and collides with autopilot's parent-only interaction model
  (`ask_parent_question_kandev`).
- **S3.** `ask_user_question_kandev` SHALL remain absent from the external surface, as today.
- **S4.** Neither tool SHALL be added to the session agent system prompt, since neither is visible to
  session agents.

### `list_tasks_kandev` enrichment

- **T1.** `list_tasks_kandev` SHALL include `task_pending_action` and `primary_session_pending_action`
  for each task, using the same projection the HTTP task list already returns
  (`GetPendingActionsForSessions`, `task/dto/dto.go`), so one call finds every blocked task in a
  workflow.
- **T2.** A task with no blocked session SHALL carry JSON `null` for both fields rather than an empty
  string, matching the HTTP DTO — both fields are `*string` with no `omitempty`, so the key is always
  present and its value is `null`.

### Catalog and documentation

- **C1.** `apps/web/lib/settings/external-mcp-tools.ts` SHALL list both new tools with localized
  descriptions, in a group whose title reflects answering agent questions.
- **C2.** The catalog's KNOWN DRIFT SHALL be closed in the same change. The backend's external tool
  count and the catalog's pinned count SHALL be re-derived against the post-rebase `main` at
  implementation time and made equal; the stale drift note in both
  `external-mcp-tools.ts` and `external-mcp-tools.test.ts` SHALL be **deleted rather than
  renumbered**. The first version of this spec pinned the arithmetic at 35 → 37 and 30 → 37 against
  the pre-rebase merge base; upstream has since landed 60+ commits, so those literals are recorded
  here as **provenance, not as targets**, and a builder SHALL read the live values from
  `TestServerModeExternal_ToolCount` and `countExternalMcpTools()` instead of trusting them.
- **C3.** Every new catalog entry SHALL resolve to an existing `en/settings.json` key, per the
  existing pinning test.

## Permissions

This spec introduces no new permission concept. It applies the existing per-user workspace scoping
rule (`apps/backend/AGENTS.md`, "Opt-in authentication & per-user scoping") to a service that missed
it:

- No identity in context, or a synthetic identity → unscoped, today's pre-auth behavior.
- Real identity → the bundle is visible if the workspace owning its task has an empty `owner_id` or
  an `owner_id` matching the caller, **and also** in the two further cases `authorizeTaskID` itself
  allows: the task has no workspace, or the task's workspace row does not exist. **L1c is the
  normative statement** and the list tool's query predicate SHALL be written against it.
- Denial uses the not-found sentinel (`repoerrors.ErrTaskNotFound` via `AuthorizeTaskAccess`), so a
  foreign bundle and a missing bundle are indistinguishable.

The authorization input is the `pending_id` → `task_id` mapping read from the durable messages (M5).
It SHALL NOT be read from a caller-supplied `task_id`; a caller that supplies one alongside a
`pending_id` has it ignored.

External MCP callers reach this check because `DispatcherBackendClient.RequestPayload` passes the
HTTP request context — carrying the identity the auth middleware attached — straight into `Dispatch`.

**An earlier proposal to authorize via the MCP scope resolver was wrong.** `internal/mcp/scope`
attaches the owning identity of an in-session agent stream; it neither resolves a `pending_id` nor
authorizes one, and it does not apply to the external endpoint at all.

## Failure modes

- **Two callers answer the same active bundle.** Upstream's claim admits one. The winner runs step 5;
  the loser takes R2's winner branch and receives the winner's status and reconstructed answers with
  `claimed: false`. No transcript overwrite, no second resume.
- **A caller answers a bundle whose turn has been superseded.** The claim's current-turn predicate
  rejects it, no message carries a terminal status, and R2's second branch returns 409. This is a
  deliberate narrowing relative to the first version of this spec, which would have answered it and
  resumed the agent in a new turn; upstream's approved contract states superseded rows "cannot drive
  ... a late agent resume", and this spec defers to it rather than reopening that decision.
- **A caller answers a bundle whose session has reached a terminal state.** Same path, same 409. The
  first version of this spec explicitly allowed this ("the transcript is a record, not a live
  channel"); that promise is withdrawn for the same reason.
- **A caller answers a detached bundle on the current turn.** Detachment sets `agent_disconnected`
  without changing `status`, so the bundle is still active: the claim succeeds and upstream's
  bounded-wait detached-resume dispatch runs. This is the "the agent moved on but the answer still
  matters" case, and it still works.
- **A backend restart strands a bundle.** A restart does not by itself end a turn or terminate a
  session, so the bundle remains active, is still listed by L1, and is still answerable (R6).
- **The resume dispatch cannot be accepted.** Upstream rolls the claim back via
  `RestoreActiveClarificationBundle` and the endpoint returns a server error; the bundle becomes
  answerable again. This spec adds nothing here and deliberately reports no partial-success state.
- **A bundle's messages carry no `question_id`.** L16 excludes it from L1 and rejects it before the
  claim, because upstream's claim would abort mid-transaction. It is visible in the transcript and
  clearable only by whatever upstream's lifecycle does to it (expiry on session teardown, or
  supersession by a newer turn).
- **A bundle's `task_id` resolves from neither source.** M5a: not-found for scoped callers, omitted
  from L1 for every caller. Answerable by an unscoped caller whenever upstream's claim still accepts
  it. Near-degenerate in practice, since `task_session_messages.task_session_id` is FK-constrained.
- **A bundle's session row is deleted.** The session cascade removes the bundle's messages, so step 1
  finds nothing and the answer returns not-found (A5) — the same response as an unauthorized bundle,
  by design. Deleting a task deletes its sessions, so this is also the deleted-task path.
- **The loser's re-read races another transition.** R2a: one read, no retry, report what was seen.

## Scenarios

1. **External agent answers a live question.** Agent A on task T calls `ask_user_question_kandev` and
   blocks. An external client lists pending questions, sees T's bundle with its option IDs, and calls
   `answer_question_kandev`. The claim commits, the in-memory waiter is delivered, and agent A's
   blocked tool call returns the answers **in the same turn**. The chat overlay closes for anyone
   watching, via the existing `session.message.updated` broadcast.

2. **Human and external agent answer simultaneously.** The human clicks Submit while the external
   client posts a different answer. One claim wins. The winner's answers reach agent A and appear in
   the transcript. The loser gets a 200 with `claimed: false` and the winner's payload; the losing tab
   renders the winner's answers, not its own (W3); no second turn starts, no transcript overwrite.
   **This is the race no test in the tree can currently exercise**, because the MCP answerer did not
   exist when upstream's tests were written (R3).

3. **Answer after a backend restart.** A bundle is created and the backend restarts, so the in-memory
   entry is gone. An external client lists pending questions — the bundle is still there, because the
   list reads durable messages (L2) and the restart did not supersede its turn. It answers; there is
   no live waiter, so upstream's detached-resume dispatch resumes the agent. A second answerer gets
   R2's winner branch rather than a second resume.

4. **Foreign bundle.** User B holds a PAT and learns a `pending_id` belonging to user A's workspace.
   `answer_question_kandev` returns not-found, identical to a fabricated ID.
   `list_pending_questions_kandev` never showed it. `GET /:id` and `GET /:id/wait` both return 404
   rather than their usual 404/504 split, because A7 puts the authorization check ahead of the
   in-memory read.

5. **Superseded bundle.** The session accepted a newer turn while an older clarification was still
   pending. The bundle is absent from `list_pending_questions_kandev`, does not block turn-complete,
   and an answer attempt returns 409 naming it as no longer active. The transcript still shows it.

6. **Auth disabled.** Identity is synthetic and every caller is unscoped, so nothing is ever denied:
   every bundle remains listable and answerable exactly as before. The six behaviors that do change
   are enumerated in A4 and change identically under enforced auth. There is one code path.

## Retired criteria

Five rounds of spec review and six Build rounds referenced the identities below. Each is withdrawn
here, with its reason, so a reader of that history can tell **retired** from **missing**. No retired
rule may be reintroduced without reopening the collision this revision resolves.

- **M1, M2, M3, M4, M6, M6a, M7, M7a, M8, M8a, M9, M10** — the entire `clarification_resolutions`
  table: its schema, FK cascade, no-backfill rule, dialect portability, response payload shape,
  `resume` write ordering, the `ON CONFLICT ... DO NOTHING` claim statement, its FK-violation and
  vanished-conflict-row edge cases, and the `source` column. **Retired: the table is not created.**
  Upstream's `CompleteActiveClarificationBundle` is the claim (P1). M6a's substance survives as
  **R12**, because the `omitempty` problem it identified is a property of `clarification.Response`,
  not of the table.
- **M5b** — the answerability split between M5a's two arms, which depended on M8a's foreign key.
  **Retired with the FK.**
- **D4/D4a's two-conjunct membership rule** — "no resolution row AND at least one effectively-pending
  message". **Retired: conjunct 1 named a row that no longer exists.** D4 now defers to upstream's
  activeness rule outright, and D4a records why no migration is needed.
- **G1, G2, G3, G4, G5** — the workflow-guard changes. **Retired: the guard is already correct.**
  Upstream repointed `sessionHasPendingClarification` at `FindActiveClarificationMessagesBySessionID`,
  which already widens `= 'pending'` to `COALESCE(status,'') IN ('','pending')` and adds current-turn
  scoping. The function G1/G4 proposed to modify no longer exists. **G5 is additionally withdrawn on
  the merits**, not merely as dead code: it required an *unrecognized* status to count as pending
  (fail closed), while upstream's shared predicate counts it as not-pending. Two consumers disagreeing
  about membership is precisely the defect G5 was written to prevent, so this spec adopts upstream's
  rule rather than diverging from it (D3).
- **R5, R5a** — partial application of per-question updates, the stop-at-first-failure prefix, and
  the 500 that reported it. **Retired: partial application is now impossible.** Upstream's claim
  writes every row of the bundle in one transaction, so a half-applied bundle cannot be produced.
  The corresponding R10 row and A4 item are gone.
- **R8, R8a, R8b, R8c** — the four-valued `resume` field and its rule ordering. **Retired: there is
  no success case in which the resume is in doubt.** Upstream's respond path returns success only
  after delivery confirmation or accepted dispatch, and rolls back otherwise (R7a).
- **R9a** — marking a bundle's messages `rejected` when they carry no `question_id`. **Retired:**
  upstream's claim refuses such a bundle entirely, so the rejection cannot land at all. L16 now
  excludes the bundle from discovery instead of promising an outcome that would 500.
- **X1, X2, X3, X3a, X4, X5** — routing `POST /:id/cancel` through the claim with
  `status = cancelled`, the losing-cancel `CancelCh` exemption, and the four-row cancel status table.
  **Retired: upstream's claim has no `cancelled` terminal status** — `CompleteActiveClarificationBundle`
  rejects any status other than `answered` or `rejected` — and adding one is a change to the
  active-lifecycle contract, not to this card. Cancel keeps its existing behavior and gains **only**
  the A2 authorization check. See *Out of scope*.
- **W3a's union widening** — adding `"cancelled"` to the client's `ResolvedStatus` union.
  **Retired: the backend can no longer return a cancelled winner** (W3a).
- **C2's literal counts (35 → 37, 30 → 37)** — **retired as targets, kept as provenance.** Upstream
  landed 60+ commits after those numbers were measured. C2 now requires re-deriving them.

## Out of scope

Each exclusion below is a decision, not an omission.

- **Answering a superseded or terminal-session bundle.** Upstream's approved active-lifecycle spec
  states superseded rows cannot drive a late agent resume, and that a terminal session's pending
  bundles expire. The first version of this spec promised the opposite. **That promise is withdrawn
  rather than fought**: upstream's spec is approved and merged, this one is draft and unmerged, and
  two contracts disagreeing about when a clarification is answerable is exactly the defect this
  revision exists to remove. Anyone who wants stale-bundle answering back should change the
  active-lifecycle contract, on its own card, with its own threat model.
- **Making cancel atomic, authorized-and-claimed, or usable on a restart-stranded bundle.** Cancel
  gains A2's authorization check and nothing else. Its existing defects — it requires a live
  in-memory entry, it applies per-question updates in a log-and-continue loop, and it cannot clear a
  bundle whose entry is gone — are untouched here because fixing them needs a `cancelled` terminal
  status in `CompleteActiveClarificationBundle`, which is upstream's primitive and upstream's
  contract. Adding a second cancel-claim in this card would violate P1 outright.
- **Resolving a bundle whose messages carry no `question_id`.** L16 excludes it. Making it resolvable
  requires upstream's claim to tolerate an empty `question_id`, which is a change to a shared
  primitive with its own lifecycle questions.
- **Storing the winner's `reject_reason` durably** so a loser can replay it. R2b reports `""`.
  Repairing it means adding a metadata key to a shape the *Upstream baseline* freezes.
- **`wait_for_question_kandev` / long-poll / push.** Deliberately dropped. It recreates the long-held
  MCP connection that `ask_user_question_kandev` already papers over with progress pings — justified
  for an agent blocked on its own question, wrong for a discovery API. Callers poll the list tool
  with a cursor. Notification is reconsidered only alongside a real subscription contract with
  reconnect and missed-event recovery; progress pings are not that.
- **A grand total in the list response.** L11a. `next_cursor` answers "is there more".
- **Extending the two tools to the in-session task surface.** Requires its own threat model (S2).
- **The clarification popup's own UX** — Escape committing a skip rather than dismissing, shortcuts
  focus-scoped to the overlay, submit gated on the whole bundle. Separate card. W4 is in scope only
  because N8b makes an over-long answer newly rejectable.
- **The Office inbox workspace leak.** `DashboardService.inboxPermissionItems` calls
  `Store.ListPendingPermissions()` with no workspace argument while every sibling call in the same
  function takes `wsID`. **Verified during this spec's input inventory**, not merely suspected:
  pending clarifications from every workspace appear in every workspace's inbox.
  `ListPendingPermissions` is also restart-lossy and option-less. It is untouched here, and this
  spec's tools deliberately do not reuse it. It needs its own card.
- **Changing `ask_user_question_kandev`'s own shape, validation, or response envelope.** Unchanged.
- **A `pending_id`-aware WS gateway backstop entry.** `Client.authorizeAction` keys off
  `task_id` / `session_id` / `id`. The new actions are reachable only through the external MCP
  dispatcher, which does not go through the gateway client, and they authorize at the service layer.
  If these actions are ever exposed over the browser WS, the backstop must learn `pending_id` first.

## Verification notes

**E2E decision.** This touches one user-visible surface: the clarification overlay in chat, via
W1–W4a. `apps/web/e2e/tests/chat/clarification.spec.ts` already covers the overlay end to end and
already intercepts `**/api/v1/clarification/*/respond`. Extend it with a duplicate-submit case
asserting the overlay closes on a `claimed: false` **200** and that the rendered answer is the
winner's, not the loser's (W3); do not add a new spec file. The two MCP tools have no browser surface
and need no E2E.

**Assertions that must exist.**
- **R3's cross-entry-point race is the single most important new test in this revision.** It needs a
  real two-goroutine test against a shared database in which one caller answers over the REST handler
  and the other over `answer_question_kandev`, asserting exactly one observes `claimed == true` and
  the other receives the winner's payload. A REST-vs-REST or MCP-vs-MCP race does **not** substitute:
  the collision this revision resolves was precisely two entry points claiming by different
  mechanisms, and only a cross-entry-point test proves P1 holds.
- **P1 needs a structural assertion, not only a behavioral one.** Assert that no table named
  `clarification_resolutions` is created by `initSchema` or any migration, and that the resolution
  path contains no claim statement of its own. A behavioral test passes just as well with a dormant
  second mechanism present.
- R2's two branches need separate tests: a duplicate answer against a bundle with a terminal status
  (expect 200, `claimed: false`, winner's payload) and an answer against a superseded bundle (expect
  409). A test that only covers the first would pass with the branches collapsed, which is the exact
  defect R2 exists to prevent.
- R2b needs a test that a replayed **rejection** carries `answers: []` and `reject_reason: ""`, and a
  test that a replayed **answer** carries the winner's answers in D2 order — not the loser's.
- The authorization tests (A1–A5a, A7, A8) need both the enabled and disabled auth modes, since A4 is
  the compatibility guarantee. The auth-disabled run asserts all **six** A4 carve-outs are present,
  not absent.
- A5a additionally needs an auth-**enabled** test asserting that `GET /:id/wait` returns the **same**
  status for a foreign bundle and for a fabricated `pending_id`. Asserting only the 404 on the
  fabricated id would pass even if the foreign case returned something else, which is exactly the
  oracle A5a exists to close.
- R12 needs a test asserting the response envelope contains the **keys** `answers`, `rejected` and
  `reject_reason` on every outcome — on a rejection `answers` is `[]` and present, on an answer
  `rejected` is `false` and present. Assert key *presence* explicitly (`json.RawMessage` / map
  lookup), not the unmarshalled Go value: unmarshalling an absent key yields the same zero value as
  an emitted empty one, so a test that only reads the struct back passes against the exact bug R12
  exists to prevent.
- L16 needs a test that a bundle with an empty `question_id` on any message is absent from
  `list_pending_questions_kandev` **and** that answering it returns the pre-claim validation error
  rather than a 500 from upstream's aborted transaction.
- L2a needs a test that a superseded bundle and a terminal-session bundle are both absent from the
  list, proving the tool uses upstream's activeness predicate rather than a status-only filter.
- L1a needs a test with more matching bundles than `limit` across two workspaces, asserting the page
  is full rather than short.
- N3a needs a test that two differently-ordered but semantically identical submissions produce
  byte-identical answer payloads, and one proving N3a rule 3's ordering: a `custom_text` of exactly
  2001 runes with a trailing space is **rejected**, not trimmed to 2000 and accepted.
- N8b needs both boundary tests: exactly 2000 runes accepted, 2001 rejected, counted over code points
  with a multi-byte fixture.
- N8d needs per-rule isolation tests only. A test asserting which error wins among simultaneous
  violations SHALL NOT be written; it would pin an unspecified behavior.

**Tests that need deliberate re-derivation against upstream.** The first version of this spec was
built and reviewed across six Build rounds. The following existing artifacts test the retired
mechanism and SHALL be re-derived or deleted rather than rebased: `internal/clarification/resolver_test.go`
and `resolver_restart_test.go`'s claim assertions, `internal/task/repository/sqlite/clarification_resolution_test.go`
and its Postgres sibling in full, and the `clarification_bundle_query_*` tests' D4a-conjunct-1 arms.
`handlers_authz_test.go`, `outcome_validation_test.go`, `question_handlers_test.go`, and
`task_pending_actions_enrich_test.go` test criteria this revision keeps and should largely survive.

**Tests that need deliberate updating.**
- `internal/mcp/server/server_test.go` — `TestServerModeExternal_ToolCount` moves to the re-derived
  post-rebase count (C2).
- `internal/mcp/server/external_integration_test.go` — its `NotContains "ask_user_question_kandev"`
  assertion stays **true and unchanged** (S3); add positive assertions for the two new tool names.
- `apps/web/lib/settings/external-mcp-tools.test.ts` — the pinned count moves to the re-derived value
  and the stale drift note is deleted (C2).
- Any test asserting a **409** from `POST /:id/respond` on a duplicate submit moves to 200 with
  `claimed: false`; tests asserting 409 for a genuinely inactive bundle stay (R11).
- `internal/mcp/handlers/handler_inventory_test.go` measures the dispatcher delta dynamically and
  needs **no** change when handlers are added.