werkregie/doc/prs/2026-10-12-PR#40-your-turn-claude.md

PR#40: Du bist dran Shows a Claude Code Session That Waits for the User

WARNING: This document describes only the change applied in this PR. It may already be outdated once the next PR is merged. Historic PR documentation is not maintained along with new PRs; treat it as a snapshot.

Problem

"Du bist dran" lists pull requests and Matrix messages, but no Claude Code session that waits for the user. A session that asks a question stays unnoticed until the user looks into Claude Desktop.

A measurement on think on 2026-10-12, over the turns of 7 days and a sample checked by hand, showed:

• Claude Code marks a session that blocks on the user in its process file: status waiting, with waitingFor, e.g. input needed for an open AskUserQuestion, or dialog open. This was right in both live cases.
• A closed session keeps its unanswered AskUserQuestion only in its transcript.
• About 450 of 1566 turns ended with an AskUserQuestion; many more asked in the text, e.g. with options A, B and C, or "Schick mir die Ausgabe".
• Jev rated the last message of an idle session well: all 40 turns with a question or a request rated at least 0.79, 11 of the 12 others that it rated at least 0.8 asked the user indeed, and all below 0.5 did not. One call takes about 350 ms and costs about 0.00004 USD.
• A session whose last activity is newer than its last focus asked the user in only 2 of 5 cases; "unread" is no criterion for "your turn".

Non-Goals

• No change to the session cards below "Du bist dran". As before this PR, they mark every idle session with the words "wartet auf dich", whether it asks something or not.
• No Codex threads.
• No rating of sessions that are archived or older than the window.
• No reply to a session from the dashboard.

Specification

Feature: Du bist dran shows a Claude Code session that waits for the user

Scenario#40.01: a question of Claude is due

… so that the user answers a question without looking into Claude Desktop.

• Given a Claude Code session that waits with input needed
• When the dashboard reads the sessions
• Then "Du bist dran" lists the session under "Antworten" with "Frage offen"

Verified by

• ClaudeCodeSourceTest "a session that waits for the user asks for an answer"

Scenario#40.02: an open dialog is due

… so that a permission prompt does not hold a session unnoticed.

• Given a Claude Code session that waits with dialog open
• When the dashboard reads the sessions
• Then "Du bist dran" lists the session under "Antworten" with "Dialog offen"

Verified by

• ClaudeCodeSourceTest "a session that waits for the user asks for an answer"

Scenario#40.03: a closed session keeps its question

… so that a question is not lost when its process ends.

• Given a closed Desktop session whose transcript ends with an unanswered AskUserQuestion
• When the dashboard reads the sessions
• Then "Du bist dran" lists the session with "Frage offen"

Verified by

• ClaudeCodeSourceTest "an unanswered question in the transcript asks for an answer"

Scenario#40.04: a question in the text is due

… so that a question without AskUserQuestion reaches the user too.

• Given an idle Claude Code session whose last message asks the user a question in its text
• When Jev rates this message at 0.9, above the threshold of 0.75
• Then "Du bist dran" lists the session under "Antworten" with "wartet auf dich"

Verified by

• ClaudeCodeSourceTest "Jev decides on the last message of an idle session"

Scenario#40.05: a report is not due

… so that finished work does not crowd "Du bist dran".

• Given an idle Claude Code session whose last message only reports finished work
• When Jev rates this message at 0.3, below the threshold of 0.75
• Then "Du bist dran" does not list the session

Verified by

• ClaudeCodeSourceTest "Jev decides on the last message of an idle session"

Scenario#40.06: the user's own message is not rated

… so that a session where the user spoke last costs nothing and shows nothing.

• Given an idle session whose transcript ends with a message of the user
• When the dashboard reads the sessions
• Then the session has no marker, and Jev is not asked

Verified by

• ClaudeCodeSourceTest "only the last message of Claude is rated, once"

Scenario#40.07: each message is rated once

… so that the polling every few seconds does not cost a call each time.

• Given an idle session whose last message Jev rated before
• When the dashboard reads the sessions again
• Then Jev is not asked again

Verified by

• ClaudeCodeSourceTest "only the last message of Claude is rated, once"

Scenario#40.08: without Jev, the process file and the transcript decide

… so that the dashboard sends no chat text unless configured.

• Given a dashboard whose configuration does not name Jev
• When an idle Claude Code session ends with the text "Soll ich den PR anlegen?"
• Then "Du bist dran" does not list the session

Verified by

• ClaudeCodeSourceTest "Jev decides on the last message of an idle session"

Solution

• ClaudeCodeSource gives a session that is not busy the marker ask, by the first that applies:
  1. the process file says waiting: "Frage offen" for input needed, "Dialog offen" for dialog open, else the raw waitingFor;
  2. the tail of the transcript holds an AskUserQuestion without a result: "Frage offen";
  3. Claude spoke last and Jev rates the last text at least threshold, default 0.75: "wartet auf dich".
• The transcript is ~/.claude/projects/*/<session>.jsonl; only its last 512 KiB are read.
• An archived session carries no marker; archiving it in Claude Desktop removes it from "Du bist dran".
• Jev gets the last 3000 characters of the text as message, with one noul question. Its answer is kept per message, so each message costs one call. After a failure, Jev is asked again only after 60 s; until then, rule 3 does not apply.
• Configuration claude.jev with apiKeyEnv, e.g. TYPESAFE_API_KEY in the relay's dashboard.env; without it, no chat text leaves the machine.
• The page lists sessions with ask in the group "Antworten" of "Du bist dran" and opens them in Claude Desktop.
• Version 0.21.0.

Open Questions

• Hard criteria only, or Jev too? Both, chosen by the human after the measurement above; the hard criteria cover only about a third of the turns that ask the user.
• Which threshold? 0.75: in the sample it kept the real requests at 0.78 and 0.79, and let the optional hints at 0.54 and 0.55 pass.

Follow-up PRs

• The session cards could say "wartet auf dich" only for a session with the marker ask.