Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions .changeset/claude-code-agent-session-state-opt-out.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
---
"@flow-state-dev/claude-code": minor
---

`claudeCodeAgent` and `createClaudeCodeAgentCapability` take `sessionState: false`,
so the agent can run as background work on a task board (LAB-133).

The agent normally keeps two things in session state: the SDK session id it
resumes on the next request, and a log of the run handles it has returned. A
background job is one run in one child session, so nothing on that path reads
either back — and the task board refuses to build a background worker whose block
declares session state at all, because those workers share one flow and would
overwrite each other's keys. Until now the agent could not be dispatched as one.

Setting `sessionState: false` suppresses three things together: the declaration,
the reads and writes that go with it, and the SDK `resume`. The provider is not
consulted, so a custom session provider cannot hand back a saved id that silently
resumes a prior conversation. Everything else is unchanged — the items the run
emits, the handle it returns, and how failures surface are identical.

The capability honours it too, and has to: it declares the same schema separately
from the block, through a channel the board's check cannot see.

Default is `true`, so callers who do not set it are unaffected in every respect.
2 changes: 2 additions & 0 deletions apps/docs/docs/server/background-work.md
Original file line number Diff line number Diff line change
Expand Up @@ -258,6 +258,8 @@ labels, timestamps and status. Fetch the session itself if you need more.
- [Work that outlives the turn](/guides/background-work) — how jobs relate to the other
things this framework calls background work
- [Client overview](../client/overview.md#background-work) — the same two calls from an app
- [Claude Code SDK agent](../tools/claude-code-sdk.md#turning-it-off-for-background-work) — running
a coding agent as a job, and what its workstream records
- [Server setup](./setup.md) — the full HTTP route table
- [Authentication](./authentication.md) — how addressed routes scope by owner
- [Persistence](../persistence/overview.md) — where sessions and requests are stored
24 changes: 24 additions & 0 deletions apps/docs/docs/tools/claude-code-sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,30 @@ a live handle across requests rather than a parallel store. The default provider
is thin because the SDK resumes cheaply by id; pass your own to hold a heavier
resource (an open connection, for example).

### Turning it off for background work

A **workstream** is a child session dedicated to one background job, running
outside the request that started it. If you dispatch the agent into one, set
`sessionState: false`:

```ts
const agent = claudeCodeAgent({ sessionState: false });
```

Each job is then one run. The agent starts fresh every time, no session id is
stored, and no prior SDK conversation is resumed — a second job addressed to the
same workstream begins a new agent run. What the run did is still recorded: the
workstream's own item stream holds its messages, reasoning, and tool calls in
order, which is what you read the run back from.

The option is also required rather than optional there. Background workers share
one flow, so two of them declaring the same session-state key would overwrite
each other; the task board refuses to build a background worker that declares
session state at all, and this is how the agent satisfies it.

See [Background work](../server/background-work.md) for how a workstream is set
up and read back.

## Tool approval

By default the agent governs its own tools through the SDK's `permissionMode`. To
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"topic": "kestrel-ledger",
"outputFileName": "kestrel-ledger.txt",
"marker": "ORBIT-SEVEN-KESTREL",
"secondLine": "compiled by the harness workstream"
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# harness-workstream › it mirrors a coding run as workstream items

**Issue:** LAB-133
**Outcome:** You can hand a coding job to an agent, get your request back straight away, and
afterwards say what the run did without ever opening the harness transcript. The run has its own
place in the system — a background job attached to the conversation that started it — and its
top-level activity is readable, in order, from state alone.
**Input:** `fixtures/input.json` — the workstream topic, the file the run is asked to write, the
marker line it must write into it, and the second line. Held out: every assertion keys on these
values round-tripped through the real dispatch, so a different valid fixture must still pass a
correct implementation.
**Signal:** A workstream row appears under the originating session (`{ workstreams: [...] }`,
carrying the held-out topic and a different session id), and
`GET /sessions/:childId/requests?include_items=true` returns that run's top-level `message` and
`tool_output` items, in non-decreasing sequence, with the run's activity preceding the report it
wrote about that activity, and naming the held-out file somewhere in what the run said **or** did
(the tool call's own arguments count — keying this on the closing sentence alone grades the
model's phrasing rather than the mirror, and did fail a run that had mirrored the job perfectly).
The same read *without*
`include_items=true` must return no items — otherwise the adapter is ignoring the flag and the
readback proves nothing. The originating request's own stream must carry none of the run's
mirrored items (`message` / `reasoning` / `tool_output` / `container`, or anything attributed to
the agent block). Asserted on item kind, not on marker text: the marker is part of the job the
conversation wrote, so it legitimately appears in the parent's stream when the board publishes
the filed row.
**Anti-game:** Must not read the SDK transcript, the working tree (including the file the run was
asked to write), or git. Must not assert on whether the coding agent did a **good** job — that is
LAB-135's question. Must not assert on **how the run was settled** — the task row's status, the
workstream request's status, retries, or whether a lost run stayed recoverable. Settlement is
deliberately out of scope (FIX-1182); this board takes the task board's defaults, which means a
lost run is **written off** rather than re-claimed. That is a stated gap, not a bug this goal
should be extended to cover. A run that completes with an empty item stream is a FAIL, not a pass.
**Model:** real — the Claude Code Agent SDK resolves its own model; the flow declares no
generator actions.
**Store adapter:** `@flow-state-dev/store-sqlite`, named deliberately. `withItems` is advisory and
the in-memory store ignores it by documented contract, so `include_items=true` is only observable
on an adapter that branches on the flag.
**Run:** `pnpm tsx goals/harness-workstream/mirrors-a-coding-run-as-workstream-items/run.mts`

## Verdict log
| Date | Commit | Model | Verdict | Notes |
|------|--------|-------|---------|-------|
| 2026-08-18 | f56c6b216 | claude-sonnet-5 (SDK default) | PASS | 21 items read back with `include_items=true` and 0 without; 1 top-level message, 2 top-level tool_outputs, non-decreasing sequence, naming the held-out file; the originating request carried none of the run's mirrored items |
| 2026-08-18 | f56c6b216 | claude-sonnet-5 (SDK default) | PASS | second consecutive run, same shape |
Loading
Loading