Skip to content

Build 2/7 — Stop analysis: one pure Claude module for question, permission and tool summary #75

Closed
#95
Closed
Build 2/7 — Stop analysis: one pure Claude module for question, permission and tool summary#75
#95
Labels
wayfinder:taskWayfinder task ticket

Description

@Simon-AI-coding
Simon-AI-coding
opened on Aug 25, 2026

Part of #67 · Build group 2 of 7 from the signed port table.

Rows covered

P3 pending question · P4 permission request · P5 tool summary — one optimised port for the Claude parser; P4 additionally adapts Codex to the existing v1 app-server request path (no transcript parser for Codex).

Legacy citations

  • P3: legacy@1d32845:bridge/transcript.py:1184-1259,1633-1766,1814-1858; bridge/daemon.py:2002-2045,2115-2167.
  • P4: bridge/transcript.py:1610-1713; bridge/daemon.py:183-220,1963-2052. Codex gets no transcript question parser (bridge/transcript.py:431-454 — legacy had none).
  • P5: bridge/transcript.py:126-143,1669-1675,1779-1811.

Shape (binding constraint from the table: one pure deep module)

  • adapters/agent/claude/stop_analysis.py, ≤ ~300 lines, no I/O, no socket, no store, no Core import.
  • Public interface: analyse(records: Sequence[Mapping], notification: str | None = None) -> StopAnalysis returning exactly the WaitingFor type Build 1/7 — Discovery, roster and reachability: lock the one Session-inspection type #74 locked (kind ∈ {none, question, permission, unknown}, caught_up, prompt, options: tuple[Option(text, recommended)], recommendation, tool_name, detail, approval_id): question → prompt, flattened options with per-option recommended marks and one whole-call recommendation; permission → tool_name, bounded detail (first non-blank of description, file_path, path, notebook_path, ≤ 200 chars; never command text, content or edit strings), approval_id from the hook payload when present; kind=unknown, caught_up=False when the transcript has not yet flushed the awaited record (retry later, never guess).
  • Invariants ported: pair tool_use with later tool_result in transcript order, consider only the visible tail, a readable AskUserQuestion beats a permission call beside it, a first-turn permission may take its tool name from the Notification sentence.
  • The caller (the Claude adapter's inspect) reads the transcript at the path group 1's registration supplied and passes records in; the module never opens a file.
  • Tests: table-driven over recorded transcript fragments (fixtures re-expressed from legacy test_bridge.py cases, not copied); copying transcript.py then deleting is a failed shape.

Left behind

Durable Stop Request id, catch-up cache tied to ledger rows, model-facing fragment history, the 2.9k-line module topology, full tool arguments, raw transcript blocks, any second tool-summary store; P4: the old Notification/Stop ledger and legacy approval transport (#61 R5 — none existed); the Approval request/receipt contract and hook installation stay outside the parser.

Red first

Acceptance step stop notice red before the branch; green after. Bridge Core renders the Stop Notice from the typed result (core/bridge.py:122-130,591-599 flatten-to-one-sentence goes away).

Done when

Acceptance step green on Simon's machine; pytest + ruff green; the module's public signature and line count are in the resolution comment.

Blocked by

Group 1 (locked WaitingFor fields).

Activity

  1. Simon-AI-coding
    added
    wayfinder:taskWayfinder task ticket
    on Aug 25, 2026
  2. Simon-AI-coding
    added a parent issue on Aug 25, 2026
  3. Simon-AI-coding
    marked this as blocked on Aug 25, 2026
  4. Simon-AI-coding
    marked this as blocking 3 issues on Aug 25, 2026
  5. Simon-AI-coding
    added 3 commits that reference this issue on Aug 26, 2026

    Discover Claude Sessions from the official roster, and Codex from disk (

    6503895

    Make `inspect` refuse rather than call an unread Session over (#74)

    21a3d56

    Discover Sessions, lock the one inspection type, and make a registere…

    7b0ced3

  6. Simon-AI-coding commented on Aug 26, 2026

    @Simon-AI-coding
    Simon-AI-coding
    on Aug 26, 2026
    OwnerAuthor

    Build done, reviewed, and one thing left that needs Simon

    Branch stop-analysis-75, worktree ~/Documents/coding/GPT-VoiceCoding-wt-stop-analysis-75, two commits on 7b0ced3. 1246 pytest passing, 1 skipped; ruff check . and ruff format --check . clean. Nothing on Simon's machine was changed: no bundle installed, no write to ~/.claude/settings.json, no menu-bar app touched, no engine started.

    The public signature and the line count, as this ticket asks for

    # src/gpt_voicecoding/adapters/agent/claude/stop_analysis.py
def analyse(records: Sequence[Mapping[str, Any]]) -> WaitingFor: ...
def summarise(tool_input: Any) -> str: ...

    169 implementation lines, 382 in the file. The port table's constraint is "its implementation is at most about 300 lines" (docs/port-table.md:41-46), which 169 clears; the remaining 213 lines are docstrings and the legacy citations ADR 0010 requires. Advisor ruling: report both numbers, cut nothing.

    WaitingFor is #74's, unchanged — no field added, no type widened.

    Three decisions taken before code, all with the advisor

    1. analyse lost the notification parameter this ticket locked. Nothing in v2 can fill it: this build installs two hooks, SessionStart and PermissionRequest (installation/claude_hooks.py:67-76), and no Notification hook — so the parameter would have been a route that reads as existing. The invariant it carried is adapted, not dropped: legacy scraped the tool name for a first-turn dialog out of an English sentence (legacy@1d32845:bridge/daemon.py:143-145,213-223,2049-2051) because that was all it had; PermissionRequest fires when the dialog opens, carries the same fact, and adds the approval_id legacy never had.

    2. The caller widened from inspect to discover() + the Reply Window watcher + inspect. The pure module's signature is untouched; only who calls it changed. After #74, inspect has no production caller on either path Bridge Core reads — the roster payload comes from discover() (core/bridge.py:442) and the Stop Notice from SessionStopped.waiting_for (core/bridge.py:490-498, emitted at window.py:293). Building it on inspect alone would have left both halves of this ticket's own acceptance step unfed.

    3. approval.summary_of was deleted and its field is now P5's extractor. It read command first and returned it whole, so the Approval Relay spoke a shell command into a Live Call and pushed it to a phone, while the transcript-derived WaitingFor.detail excluded exactly that — two extractors disagreeing on a safety rule, and the leaking one was on the path that speaks. P5 is the reference implementation's own rule (legacy@1d32845:bridge/transcript.py:1779-1811,126-143): first non-blank of description, file_path, path, notebook_path, ≤ 200 characters, never command text, contents or edit strings. Over the bound is passed over whole rather than cut, because a cut lands mid-secret as readily as mid-word. request_from now calls stop_analysis.summarise directly and carries the note recording the reversal.

    What was built

    • adapters/agent/claude/stop_analysis.py — pure, no I/O, no store, no Core import. One pass: tool_use paired against the later tool_result, only the visible tail counted, a readable AskUserQuestion beating a permission call beside it. Ported from legacy@1d32845:bridge/transcript.py:126-143,1477-1605,1610-1866. Dropped: the durable Stop Request id, the ledger-tied catch-up cache, the model-facing fragment history, the 2.9k-line topology, and the whole-file identity check — a pure parser has no identity to compare against, so a child's record is caught by the sidechain rule instead.
    • adapters/agent/claude/transcript.py — the lane's one opener of a transcript file, cached on (size, mtime_ns), to be shared with Build 3/7 — Progress inspection: the progress verb over the locked inspection type #76's Progress rather than opened twice. The read is ported (legacy@1d32845:bridge/transcript.py:1125-1140); the cache is new and legacy had no analogue on this lane — it read on demand at a stop (bridge/daemon.py:2115-2167), so there was nothing to cache against.
    • The ranking, which is the only judgement outside the parser: a readable question wins outright; a permission read from the record keeps its own fields and gains the dialog's approval_id; a dialog the record has not caught up with is still a stop, named from the hook payload; nothing said and no dialog leaves the roster's own word standing. caught_up=True on the third row because WaitingFor.__post_init__ (seams/agent.py:180-186) forbids any other pair, and it is true on the seam's own terms — the reader did read the record that says so, and that record is the hook payload.
    • A RUNNING Session is never read. It is not stopped on anything, and that is what keeps the five-second cadence off the hot path.

    Evidence, all read-only on this machine

    Over every real transcript here — 1,489 files, 150,681 records across the 400 most recent. No crash, and it found exactly the two real cases present:

    measured
    a real question prompt='Which color do you prefer?', options=[('Red', True), ('Blue', False)], recommendation='Red'
    a real Bash permission detail='Delete old run directory and re-stage fresh' — its description, not the command

    Through the real adapter against the live roster: discover() over the actual claude agents --json returned 6 rows for 6 live Sessions, error=None, every idle one reporting kind=none caught_up=True — a finished turn waiting on nothing, which is the answer the roster alone can never give. The one running row's transcript was never opened.

    The waiting path through discover() on those real bytes, to the sentence Bridge Core speaks:

    … stopped and may need you — Which color do you prefer?; options: Red, Blue; it recommends Red
… stopped and may need you — Bash needs your permission: Delete old run directory and re-stage fresh

    That second line is decision 3 landing on real data.

    Cost: 0.878 s cold on the largest transcript on this machine (186 MB, 722 records — a record can hold an image), 0.6 ms warm.

    core/bridge.py — already done by #74

    This ticket's Red-first line says the flatten-to-one-sentence rendering goes away. #74 already replaced it: stop_notice_for takes a WaitingFor and _stopped_on renders the typed result (core/bridge.py:110-162). Nothing to redo.

    The acceptance run: not run, awaiting Simon

    stop notice is this ticket's exit and it has not been run. The harness sends real messages from Simon's own Telegram account, requires the menu-bar app quit and the bundle installed, and needs GPTVOICECODING_TELEGRAM_TOKEN, which only he can supply. No agent authorisation substitutes for his on an action whose only veto would arrive after the messages are sent. The advisor proposed it as his proxy and withdrew, including the suggestion to look for the token in another session's environment.

    cd ~/Documents/coding/GPT-VoiceCoding-wt-stop-analysis-75
scripts/build-app.sh                 # bundle must be byte-identical or step 0 refuses
# install the bundle, quit the menu-bar app, authorise the Telegram user account
GPTVOICECODING_TELEGRAM_TOKEN=… .venv/bin/python -m pytest -m acceptance tests/acceptance -v

    Apply the split when it runs: the content half of stop notice — the notice names what the Session stopped on — is #75's exit and is demonstrated above on real bytes. The timing half (the transition firing inside the step's window; #74 measured 292 ms against a 5 s cadence) is #77's.

    Review: Codex lane, both axes, and it ends as a recorded disagreement

    Standards — four findings, all real, all closed. A missing ported/adapted/dropped citation for the new cache (CLAUDE.md:43-46, a hard violation); summary_of left as a one-line middle man; _parked_for reaching into the listener's pending set instead of asking it (now ApprovalListener.newest_for(target)); three hand-rolled roster swap/restore blocks in the tests (now one fixture).

    Spec — four findings, re-reviewed once, 0 CLOSED / 4 RETAINED, next: escalate. Ending it as a disagreement and recording both positions, which is what escalation means here:

    1. SessionStopped never fires when a Session enters waiting (window.py:293; STATUSES_MEANING_TURN_ACTIVE includes waiting). Reviewer: an implementation error in Build 2/7 — Stop analysis: one pure Claude module for question, permission and tool summary #75. Advisor, ruling: the transition is Build 4/7 — Delivery receipts and settlement: inbox receipt, Codex verified, UNKNOWN never resends #77's P2, and the duplicate-announcement it opens — AwaitingApproval and SessionStopped both escalating one permission — is Bridge Core policy the adapter may not decide. Assigned to Build 4/7 — Delivery receipts and settlement: inbox receipt, Codex verified, UNKNOWN never resends #77 with this evidence. The gap stated plainly: after Build 2/7 — Stop analysis: one pure Claude module for question, permission and tool summary #75 a question is visible on the roster row for as long as the Session waits, and is not yet announced. The permission half does reach the user, via AwaitingApproval (approval.py:489 → core/bridge.py:461). Left for Build 4/7 — Delivery receipts and settlement: inbox receipt, Codex verified, UNKNOWN never resends #77 as unmeasured: whether AskUserQuestion raises a PermissionRequest on 2.1.246. Not measured here, deliberately.
    2. No Codex change. Reviewer: P4's Codex clause is unbuilt. Advisor, ruling: the port table's P4 says "Codex's existing app-server request path stays outside the module" — it forbids a Codex parser, it does not commission a projection in a ticket whose Shape and Done-when name one Claude file. The Codex WaitingFor projection is Build 4/7 — Delivery receipts and settlement: inbox receipt, Codex verified, UNKNOWN never resends #77's, which already owns P8 and that adapter.
    3. notification absent from the signature. Decision 1 above; ruled before code.
    4. 382 lines vs "≤ ~300". 169 implementation lines; ruled to keep the prose.

  7. Simon-AI-coding commented on Aug 26, 2026

    @Simon-AI-coding
    Simon-AI-coding
    on Aug 26, 2026
    OwnerAuthor

    Why run 2 produced no verdicts — now owned by #96

    Acceptance run 1 (20260826T034302Z, commit a116c99) is the run with real
    results. Runs 2 and 3 produced no lane results at all, and the reason is not
    this ticket's:

    The Codex-lane engine did not exit on SIGTERM (journal lines 295-296:
    engine.killed reason="did not exit on SIGTERM", then engine.stopped returncode=-9). SIGKILL skips AppServerProcess.aclose()
    (adapters/codex_app_server/process.py:319-342), so the codex app-server
    it spawned was never stopped, reparented to launchd, and kept
    /tmp/gpt-voicecoding-501/codex-app-server.sock bound. Run 2 then failed
    _claim_socket_path (process.py:392-401) on both lanes, so all nine steps
    were not observed.

    Filed as #96. Advisor's ruling: not a blocker on #75, which exits on the
    content half of stop notice.

    Recorded there too: the engine's "the shared Codex app-server daemon did not
    answer" line does not measure a daemon. CodexAdapter._shared_daemon()
    (adapters/agent/codex/adapter.py:279-287) returns None unconditionally and
    deliberately, and _threads() (adapters/agent/codex/discovery.py:127-128)
    emits the fixed NO_DAEMON string on that path without dialling anything.
    Confirmed against run 1's log: the line that reports a real dial failure
    (discovery.py:132) appears zero times. The Codex lane was not running on
    degraded daemon evidence — the connection is unbuilt by design.

    eb00c95 additionally adds the INFO line on core/bridge.py::_session_stopped
    that run 1's third assertion wanted: core/escalation.py logged on retained /
    retired / failed and nothing on the success path, so a Stop Notice that worked
    left no trace in engine.log. No behaviour change. This fix has not yet been
    observed in a completed acceptance run.

  8. Simon-AI-coding
    added 2 commits that reference this issue on Aug 26, 2026

    Read what a stopped Claude Session stopped on, and say it in one type (…

    e4c3f0d

    Read what a stopped Claude Session stopped on, and say it in one type (…

    37cf18e
  9. Simon-AI-coding
    closed this as completedin #95on Aug 26, 2026
  10. Simon-AI-coding
    added 2 commits that reference this issue on Aug 26, 2026

    Read every JSONL record, name the call the dialog holds, and forget a…

    da89dbd

    Carry the user's words over a Session's own inbox, and claim only wha…

    e2090aa
  11. Simon-AI-coding
    added a commit that references this issue on Sep 5, 2026

    An engine that changes a brief's field says so, so a run can attribut…

    8a2d1ab
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    wayfinder:taskWayfinder task ticket

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions