6eaab90d9f
Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
151 lines
7.7 KiB
Markdown
151 lines
7.7 KiB
Markdown
---
|
|
status: shipped
|
|
created: 2026-07-21
|
|
updated: 2026-08-01
|
|
owner: kandev
|
|
---
|
|
|
|
# Background Work Liveness
|
|
|
|
## Why
|
|
|
|
ACP providers do not yet expose a consistent, accountable lifecycle for
|
|
subagents and other background work. Kandev can account for recognized work,
|
|
but that best-effort signal is not reliable enough to decide whether a
|
|
`RUNNING` agent can safely receive another prompt by default. Prompt admission
|
|
and operator-visible busy state therefore use the durable coarse session
|
|
lifecycle unless a deployment deliberately enables the Claude-only experiment.
|
|
|
|
## What
|
|
|
|
- Every `RUNNING` session is busy, rejects direct prompt admission, and routes
|
|
composer input through the queued-message path by default.
|
|
- Every `RUNNING` session is shown as generating. Background-work accounting
|
|
does not select a separate operator-visible activity tier by default.
|
|
- A settled session follows its coarse state and does not remain visually busy
|
|
solely because detached work is still registered.
|
|
- Session status surfaces do not infer that an agent needs an answer from the
|
|
coarse `WAITING_FOR_INPUT` state alone. A clarification question or permission
|
|
indicator requires the corresponding pending input record; an idle session
|
|
that is merely ready for another prompt does not show either indicator.
|
|
- The runtime retains one registration per recognized live subagent and derives
|
|
`active_subagent_count` from those registrations. Background shells and
|
|
Monitor watches may remain internally tracked but do not contribute to the
|
|
subagent count.
|
|
- Adapter attestation is accounting evidence only unless the
|
|
`features.claudeBackgroundPromptHandoff` experiment is enabled for a
|
|
`claude-acp` session.
|
|
- When that experiment is enabled, all Claude modes covered by ADR-0049 retain
|
|
their fine-grained behavior: subagents, `run_in_background` shells, and
|
|
Monitor watches may expose background activity and a generation-matched
|
|
foreground handoff may admit the next prompt.
|
|
- Non-Claude providers remain coarse even when the experiment is enabled.
|
|
- The experiment is off in every embedded profile, high risk,
|
|
restart-required, and available through
|
|
`KANDEV_FEATURES_CLAUDE_BACKGROUND_PROMPT_HANDOFF`.
|
|
- Terminal execution teardown retires every tool-ownership and background-work
|
|
entry owned by that execution. It releases the whole session activity record
|
|
when no successor execution or in-flight prompt/dispatch token still owns it.
|
|
|
|
## API surface
|
|
|
|
- A `RUNNING` session record, boot payload, activity notification, or state
|
|
notification exposes `foreground_activity=generating` by default. An
|
|
eligible session in the enabled Claude experiment may expose `background`.
|
|
- Settled session records omit `foreground_activity`; task records aggregate
|
|
only coarse running activity.
|
|
- `session.activity_changed` carries `task_id`, `session_id`,
|
|
`foreground_activity`, and `active_subagent_count`. Its activity is
|
|
`generating` while the session is running; count-only changes may publish
|
|
without an activity-tier change.
|
|
- Session records, boot payloads, activity/state notifications, task records,
|
|
and `task.updated` expose `active_subagent_count` as an integer. It is zero
|
|
when no adapter-attested subagent is live.
|
|
|
|
## State machine
|
|
|
|
| Coarse state | Prompt admission | Operator activity |
|
|
| --- | --- | --- |
|
|
| `RUNNING` | Queue/reject by default; enabled Claude handoff may accept | generating by default; enabled Claude may show background |
|
|
| `WAITING_FOR_INPUT`, `COMPLETED`, or `IDLE` | Accept | omitted |
|
|
| `STARTING`, `CREATED`, `FAILED`, or `CANCELLED` | Reject as not promptable | omitted |
|
|
|
|
The background-work tracker may still transition internally between foreground
|
|
ownership and recognized background liveness. Those transitions do not change
|
|
the table above.
|
|
|
|
## Failure modes
|
|
|
|
- With the experiment off, missing, delayed, duplicated, or provider-specific
|
|
background lifecycle frames cannot make a `RUNNING` session promptable.
|
|
- With the experiment on, only adapter-attested Claude lifecycle frames can
|
|
relax the gate. Missing provider identity and every non-Claude provider fail
|
|
closed.
|
|
- A normalized tool-card shape cannot attest to promptability.
|
|
- Codex child thread/session identity and Claude task notifications may be used
|
|
for presentation or accounting, but neither changes the coarse admission
|
|
rule.
|
|
- Count drift is prevented by deriving `active_subagent_count` from the live
|
|
registration map rather than maintaining an independent counter.
|
|
- Execution completion, stop, failure, cancellation, crash cleanup, forced
|
|
cleanup, and session removal retire activity owned by that execution.
|
|
|
|
## Persistence guarantees
|
|
|
|
Background-work accounting is in memory and authoritative only while the owning
|
|
agent execution remains connected. A restart does not reconstruct detached work
|
|
or active subagent counts. Durable coarse session state remains the source of
|
|
truth for prompt admission and operator-visible activity.
|
|
|
|
## Scenarios
|
|
|
|
- **GIVEN** the experiment is off and a `RUNNING` session's tracker reports
|
|
foreground-idle with recognized background work, **WHEN** the operator
|
|
submits a prompt, **THEN** Kandev queues it.
|
|
- **GIVEN** the experiment is on for a `claude-acp` session and its tracker
|
|
reports adapter-attested background work plus a generation-matched foreground
|
|
handoff, **WHEN** the operator submits a prompt, **THEN** Kandev dispatches the
|
|
successor without queueing it.
|
|
- **GIVEN** the experiment is on for any non-Claude provider, **WHEN** the same
|
|
tracker-shaped activity is observed, **THEN** Kandev still queues the prompt.
|
|
- **GIVEN** the same session is rendered or freshly reloaded, **WHEN** its
|
|
activity is serialized, **THEN** it is shown as generating rather than
|
|
background-running.
|
|
- **GIVEN** two adapter-attested subagents and one background shell are live,
|
|
**WHEN** activity is serialized, **THEN** `active_subagent_count` is two while
|
|
the session's operator activity still follows its coarse state.
|
|
- **GIVEN** the session leaves `RUNNING`, **WHEN** its DTO or task aggregate is
|
|
serialized, **THEN** foreground activity is omitted even if detached work
|
|
remains registered.
|
|
- **GIVEN** a session is `WAITING_FOR_INPUT` with no pending clarification or
|
|
permission, **WHEN** the user opens the task add-panel menu, **THEN** the
|
|
session row shows neither the clarification-question icon nor the
|
|
permission-question icon.
|
|
- **GIVEN** an input-capable session has a pending clarification or permission,
|
|
**WHEN** the user opens the task add-panel menu, **THEN** its session row shows
|
|
the corresponding question or shield-question indicator.
|
|
- **GIVEN** an execution terminates with orphaned tool ownership and background
|
|
work, **WHEN** teardown runs, **THEN** its owned accounting state is released.
|
|
|
|
## Out of scope
|
|
|
|
- Mid-turn steering, including the steer-capable case. Delivering input into a
|
|
turn that is still generating is specified separately in
|
|
[mid-turn-steering](mid-turn-steering.md); this spec covers only the
|
|
foreground-idle handoff, where the foreground has already yielded to
|
|
recognized background work.
|
|
- Reconstructing detached-work liveness after restart.
|
|
- Rendering active subagent counts or individual subagent details in the UI.
|
|
- Renaming the generic `WAITING_FOR_INPUT` lifecycle state or redesigning status
|
|
labels and icons outside the task add-panel menu.
|
|
|
|
## Decision record
|
|
|
|
[ADR-2026-07-28 — Restore Coarse Running Prompt Admission](../../decisions/2026-07-28-coarse-running-busy-signal.md)
|
|
supersedes the operator policy in
|
|
[ADR 0049 — Fine-grained foreground-idle busy signal](../../decisions/0049-fine-grained-foreground-idle-busy-signal.md).
|
|
|
|
## Implementation plan
|
|
|
|
[Coarse running busy signal fix plan](../../plans/coarse-running-busy-signal/plan.md)
|