kankaku-claude 1.2.0 → 1.3.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kankaku",
   "description": "Records how long Claude Code works on each of your prompts: wall time, waiting time, work time and cost, per prompt, in kankaku's worklog format.",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "author": {
     "name": "soyunninja"
   },

package/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## 1.3.0 — 2026-09-29
+
+### Added
+
+- **Tokens on every record.** The input, output, cache read and cache write
+  tokens are read from the session transcript (and from each subagent's
+  transcript), so `cache hit` now appears for Claude Code records. Only new
+  bytes are read at each settle, at most 16 MiB; `UserPromptSubmit` only
+  `stat`s the files and the other hooks read nothing.
+- **`agentVersion`.** Claude Code's version, taken from the transcript.
+- **Cost for headless runs.** A `claude -p` session keeps each settled prompt
+  pending and writes its record at `SessionEnd` (or in crash recovery) with
+  the transcript's `cost-state` cost, through the same chained baseline as the
+  statusline cost. With several prompts the cost is shared in proportion to
+  their tokens and each record carries `costAllocated`, kept local and never
+  sent to the hub.
+- **Late transcript writes are covered.** Claude Code writes the transcript
+  asynchronously, after `Stop` has started. `Stop` polls every 25 ms and
+  reads once at least 100 ms have passed since the hook started, the size is
+  stable and an assistant line is present, giving up at 300 ms (the statusline
+  wait counts), so the last message of a prompt is not shifted into the next
+  record, a headless
+  `SessionEnd` or recovery reads once more and adds late usage to the last
+  pending prompt, and the entry point and version are also read from the
+  start of the file when no new line carries them.
+- **`model` from the transcript** (`anthropic/<message.model>`) when the
+  statusline gave none.
+- Any surprise in the (undocumented) transcript format leaves the record as it
+  was before: written, without tokens, version or cost, and no hook fails.
+
 ## 1.2.0 — 2026-09-29
 
 No changes in this package's code; released in lockstep with kankaku 1.2.0.

package/README.md

@@ -17,7 +17,9 @@ One record per user prompt, appended to `<KANKAKU_DIR>/worklog.jsonl`:
   waiting on a permission dialog.
 - **Work time** — wall time minus waiting time.
 - **Cost** — the prompt's share of the session's running `total_cost_usd`
-  (see "Limitations" below for how this is derived).
+  (see "How cost is derived" below).
+- **Tokens** — input, output, cache read and cache write tokens, read from
+  the session transcript (see "What is read from the transcript").
 
 Records are written in kankaku's own `WorkRecord` schema
 (`WORK_RECORD_SCHEMA = 1`), the exact one the kankaku pi extension writes to
@@ -28,9 +30,10 @@ manual and best-effort automatic hub sync through kankaku's public hub adapters
 Every record carries the identity of who measured it: `agent: "claude-code"`,
 `plugin: "kankaku-claude"` and `pluginVersion` (this package's version).
 A worklog synced by another tool, such as the kankaku TUI, therefore keeps
-the right agent on the hub. `agentVersion` is left unset because Claude Code
-does not pass its version to hooks. Records written before this version carry
-no identity and are labelled by whichever tool syncs them first.
+the right agent on the hub. `agentVersion` is Claude Code's version, read
+from the session transcript; it is left unset when the transcript cannot be
+read, never guessed. Records written before this version carry no identity
+and are labelled by whichever tool syncs them first.
 
 ## Requirements
 
@@ -268,9 +271,9 @@ later sync does not move it.
 
 ## How cost is derived
 
-Claude Code hooks carry no cost. The only source is the statusline, whose
-`cost.total_cost_usd` is the running total of the session; the statusline
-command stores the latest value under your home directory (see "Where the
+Claude Code hooks carry no cost. For interactive sessions the only source is
+the statusline, whose `cost.total_cost_usd` is the running total of the
+session; the statusline command stores the latest value under your home directory (see "Where the
 files live").
 
 - **Per-prompt difference.** A prompt's cost is the session total when the
@@ -291,12 +294,117 @@ files live").
 - **Counter reset.** If the total is lower than the value the prompt is
   measured from, the counter was reset: the prompt's cost is the new total
   and the baseline restarts from it.
-- **Headless runs have no cost.** `claude -p` renders no statusline, so
-  there is no total: the record stays without cost (`costObserved` unset)
-  and the baseline does not move.
+- **Headless runs take their cost from the transcript.** `claude -p` renders
+  no statusline, so the cost comes from the transcript's `cost-state` line
+  instead (see "Headless runs" below).
 - `/kankaku:status` shows `recorded $X of $Y` per live session so a gap is
   visible.
 
+## What is read from the transcript
+
+Every hook receives `transcript_path`, the JSON Lines file Claude Code keeps
+for the session. kankaku-claude reads it for three things, and nothing else:
+
+- **Tokens.** The `input_tokens`, `output_tokens`, `cache_read_input_tokens`
+  and `cache_creation_input_tokens` of the assistant messages become the
+  record's `usage.input`, `usage.output`, `usage.cacheRead` and
+  `usage.cacheWrite`, which is what makes `cache hit` appear for Claude Code
+  records in the `kankaku` CLI. Claude Code writes one message over several
+  adjacent lines whose usage grows (the earlier lines are partial snapshots;
+  subagent transcripts show it clearly), so each `message.id` is counted once,
+  by its last line. When a read ends in the middle of a message, the stored
+  position remembers the message id and what was counted for it, and the
+  next read adds only the growth.
+- **The version.** The `version` of the first line read becomes the record's
+  `agentVersion`.
+- **For headless runs, the cost.** See "Headless runs" below.
+
+Only numbers, the version and the entry point (`cli` or `sdk-cli`) are taken
+from a line; prompts, answers, tool inputs and outputs are never kept, copied
+or sent anywhere. Subagents do not appear in the session's transcript: each
+has its own file under `<session id>/subagents/`, and those files are read
+too, so the record of a prompt includes its subagents' tokens.
+
+How it is read:
+
+- **Only what is new.** The session state keeps a read position per
+  transcript file. `UserPromptSubmit` only records the current size of each
+  file (a `stat`, no read) so a session that already existed does not read
+  its history; `Stop`, `SessionEnd` with an open prompt and crash recovery
+  read the bytes after the position, count them and advance it. A subagent
+  file that appears later is read from its start, and a partial last line is
+  left for the next read.
+- **Tokens between two prompts are not lost.** Positions only advance when a
+  record is settled, so tokens spent after `Stop` and before the next
+  settle (a background subagent that keeps running) land in the next record
+  of the session, the same rule as cost.
+- **The transcript is written asynchronously.** Measured on real runs, the
+  last assistant lines reach the disk shortly AFTER the `Stop` hook has
+  started (none at 0 ms, present at 50 ms). Before reading at settle,
+  `Stop` therefore polls the transcript every 25 ms, measured from when the
+  hook process started, and reads once ALL hold: at least 100 ms have
+  passed (earlier assistant messages of the same prompt are usually on disk
+  long before, and the last one is the late one, so a line being present is
+  not enough), the size did not change across two polls, and the new bytes
+  hold a complete assistant line. It gives up 300 ms after the hook started
+  whatever it sees. Time already spent in the statusline wait counts, so a
+  hook that waited 300 ms or more for the statusline does not wait again.
+  Usage that still arrives   later is counted by the next settle. A headless session reads once more at
+  `SessionEnd` (or in recovery, which does not wait: the file is final) and
+  adds what it finds to the last pending prompt, since late lines belong to
+  the prompt that just settled.
+- **The model.** When the statusline gave no model (headless runs, or no
+  statusline), the record's `model` is `anthropic/<message.model>` of the
+  last assistant line, the same `anthropic/` prefix the statusline model gets.
+  The statusline model wins when there is one.
+- **A bound per settle.** At most 16 MiB of transcript is read per settle,
+  across all files. If a settle finds more new content than that, it is
+  skipped without counting and the record simply has no tokens; the hook
+  never risks its timeout on a huge file.
+- **Hooks that build no record read nothing.** `PreToolUse`, `PostToolUse`,
+  `PermissionRequest`, `SubagentStart` and `SubagentStop` never touch the
+  transcript, and `UserPromptSubmit` only `stat`s it.
+
+The transcript format is internal and undocumented and may change with any
+Claude Code release. kankaku-claude therefore treats every part of it as
+optional: a missing or unreadable file, a line it does not understand, or a
+field of an unexpected type is ignored, and the record is written exactly as
+it was before this existed, without the tokens or the version. It never makes
+a hook fail.
+
+### Headless runs
+
+A session whose transcript says `entrypoint: "sdk-cli"` (a `claude -p` run)
+has no statusline. Claude Code appends a `cost-state` line with the session's
+total cost to the transcript only after the last `Stop`, so for these
+sessions:
+
+1. `Stop` does not write the record. The settled prompt (times, waiting and
+   tokens are final) is kept in the session state as pending.
+2. `SessionEnd` reads the last `cost-state`, applies the same chained
+   baseline as the statusline cost, and appends the record with the cost and
+   `costObserved`. If `SessionEnd` never runs, crash recovery writes the
+   pending records the next time another session starts, reading the
+   transcript then. Either way each prompt is written exactly once.
+3. A `cost-state` with a finite `totalCostUSD` is usable whatever its
+   `modelUsage` holds (an empty one included); only
+   `hasUnknownModelCost: true` disqualifies it. The cost also needs a start
+   baseline: a session Claude Code reports as newly started (`SessionStart`
+   source `startup`) begins at 0; without one the cost stays unobserved,
+   like the statusline cost.
+4. With no `cost-state`, or one flagged `hasUnknownModelCost` (the total is
+   then not reliable), the records are written without cost.
+
+**Attribution.** A session with one prompt gets the whole cost. When a
+headless session ran several prompts, the total is shared in proportion to
+each prompt's token total (equal shares when all are zero), in whole
+micro-dollars with the remainder on the last prompt, so the shares add up to
+the session cost exactly. Those records carry `costAllocated: true`: the cost
+is a share, not a measured difference. The marker stays in the local
+worklog and is not sent to the hub. Interactive sessions (entry point `cli`,
+or one that cannot be read) are unchanged: the record is written at `Stop`
+with the statusline cost.
+
 ## Where the files live
 
 - `<KANKAKU_DIR>/worklog.jsonl` — the append-only log of settled records,
@@ -326,8 +434,10 @@ If Claude Code's process is killed mid-prompt (or mid-session), the next
 session's `SessionStart` hook scans for other sessions' state files whose
 process is no longer alive. A dead session with an open prompt is replayed
 and appended as one `status: "interrupted"` record before its files are
-deleted; a dead session with no open prompt just has its files deleted. This
-also runs for the current session's own leftover state at `SessionEnd`.
+deleted; a dead session with no open prompt just has its files deleted. A
+dead headless session that still holds pending prompts gets their records
+written, with the cost from its transcript. This also runs for the current
+session's own leftover state at `SessionEnd`.
 
 An interrupted prompt is closed at its last recorded activity — the
 timestamp of the last event logged for it, or its own start when nothing
@@ -340,15 +450,18 @@ still open is closed at that same instant.
 - **`turns` is always 1 per run.** Claude Code hooks give no way to observe
   provider-level retries/turns inside one run; every replayed run reports
   exactly one turn.
-- **No token counts.** Hooks never carry input/output/cache token numbers,
-  only the statusline's aggregate `total_cost_usd`; per-record `usage` token
-  fields stay at zero, cost is the only populated figure.
+- **Token counts come from an undocumented file.** Hooks carry no token
+  numbers; they are read from the session transcript, whose format can
+  change with any Claude Code release. When it cannot be read or understood
+  the record has zero tokens, and a settle that finds more than 16 MiB of
+  new transcript skips it. See "What is read from the transcript".
 - **Cost is a per-prompt delta of the session total, from the statusline,
   and needs the manual setup step.** See "How cost is derived". Spend that
   lands between two prompts (a late statusline refresh, a background
   subagent still running) is attributed to the next record of the session,
-  not lost. Headless `claude -p` runs have no statusline, so their records
-  carry no cost.
+  not lost. Headless `claude -p` runs have no statusline; their cost comes
+  from the transcript at `SessionEnd`, and is shared between prompts when
+  there are several (see "Headless runs").
 - **A permission wait ends at the next hook event, not when you actually
   click.** There is no documented hook that fires the moment you answer a
   permission dialog, so the waiting span closes at whatever hook fires next

package/dist/handle-hook.js

@@ -2,10 +2,13 @@ import { unlinkSync } from "node:fs";
 import { resolvePaths } from "./paths.js";
 import { appendEvent, readEventLog, dropSettledPrompts } from "./event-log.js";
 import { readState, writeState, updateState } from "./session-state.js";
+import { settleTranscripts, trackTranscriptAtSubmit, waitForTranscript } from "./transcript-settle.js";
 import { resolveClaudePid } from "./claude-pid.js";
 import { splitPrompts } from "./prompts.js";
 import { readCost, deleteCost, sweepStaleCostFiles } from "./cost-store.js";
 import { settleCost } from "./cost-chain.js";
+/** The transcript `entrypoint` of a headless `claude -p` run. */
+const HEADLESS_ENTRYPOINT = "sdk-cli";
 const STOP_COST_WAIT_POLL_MS = 100;
 const STOP_COST_WAIT_MAX_MS = 1500;
 /**
@@ -33,6 +36,7 @@ export async function handleHook(input, deps) {
                 : { ts, event: "UserPromptSubmit", prompt };
             appendEvent(paths.eventsFile, event);
             const snapshot = readCost(deps.env, sessionId)?.totalUsd;
+            const transcriptPath = readString(raw.transcript_path);
             updateState(paths.stateFile, (state) => ({
                 pid: state?.pid ?? 0,
                 parentPid: state?.parentPid ?? 0,
@@ -41,7 +45,9 @@ export async function handleHook(input, deps) {
                 // The chained baseline wins over the snapshot: spend since the last settle belongs to this prompt.
                 promptOpen: { id: promptId ?? `${sessionId}:${ts}`, startedAt: ts, costAtStart: state?.costBaseline ?? snapshot },
                 permissionOpen: null,
-                ...(state?.costBaseline !== undefined ? { costBaseline: state.costBaseline } : {}),
+                ...carriedOver(state),
+                // Stat only: the transcript's content is read at settle, never here.
+                ...withTranscript(trackTranscriptSafely(state, transcriptPath)),
             }));
             return;
         }
@@ -71,7 +77,7 @@ export async function handleHook(input, deps) {
                 startedAt: state?.startedAt ?? ts,
                 promptOpen: state?.promptOpen ?? null,
                 permissionOpen: ts,
-                ...(state?.costBaseline !== undefined ? { costBaseline: state.costBaseline } : {}),
+                ...carriedOver(state),
             }));
             return;
         }
@@ -93,7 +99,7 @@ export async function handleHook(input, deps) {
             const stopHookActive = raw.stop_hook_active === true;
             appendEvent(paths.eventsFile, { ts, event: "Stop", stopHookActive });
             clearPermissionOpen(paths.stateFile);
-            await handleStop(paths, sessionId, deps);
+            await handleStop(paths, sessionId, deps, ts);
             return;
         }
         case "SessionStart": {
@@ -112,32 +118,62 @@ export async function handleHook(input, deps) {
             return;
     }
 }
-async function handleStop(paths, sessionId, deps) {
+/** `startedAt` is when the hook process started: the transcript wait is measured from it. */
+async function handleStop(paths, sessionId, deps, startedAt) {
     const { replayPrompt } = await import("./replay.js");
-    const { buildClaudeRecord } = await import("./record.js");
+    const { buildClaudeRecord, stampTokens } = await import("./record.js");
     const { JsonlWorkLog } = await import("kankaku-pi/hub");
     const events = readEventLog(paths.eventsFile);
     const beforeStopTs = events.length >= 2 ? events[events.length - 2].ts : events[events.length - 1]?.ts ?? deps.now();
+    // A headless session (`claude -p`) has no statusline: its cost comes from the transcript at SessionEnd,
+    // so the statusline wait is pointless. The entry point is known after the first settle; before that, peek.
+    const opened = readState(paths.stateFile);
+    const entrypoint = opened?.transcript?.entrypoint ?? (opened?.promptOpen ? settleSafely(opened, deps)?.transcript.entrypoint : undefined);
+    const skipCostWait = entrypoint === HEADLESS_ENTRYPOINT;
     const deadline = deps.now() + STOP_COST_WAIT_MAX_MS;
     let cost = readCost(deps.env, sessionId);
-    while ((!cost || cost.updatedAt < beforeStopTs) && deps.now() < deadline) {
+    while (!skipCostWait && (!cost || cost.updatedAt < beforeStopTs) && deps.now() < deadline) {
         await deps.sleep(STOP_COST_WAIT_POLL_MS);
         cost = readCost(deps.env, sessionId);
     }
+    // Claude Code writes the transcript asynchronously: give the last assistant lines a bounded moment to land.
+    if (opened?.promptOpen)
+        await waitForTranscript(opened.transcript, deps, startedAt).catch(() => { });
+    const state = readState(paths.stateFile);
+    const transcript = state?.promptOpen ? settleSafely(state, deps) : undefined;
+    const headless = transcript?.transcript.entrypoint === HEADLESS_ENTRYPOINT;
     const prompts = splitPrompts(events);
     const last = prompts[prompts.length - 1];
-    const state = readState(paths.stateFile);
     if (!last || !state) {
         if (!state)
             deps.stderr(`kankaku: no session state at Stop for ${sessionId}`);
         return;
     }
+    if (headless && state.promptOpen) {
+        // Times, waiting and tokens are final; the cost is not known until SessionEnd. Keep the prompt and write nothing.
+        const core = replayPrompt(last, {});
+        const pending = [...(state.pending ?? [])];
+        if (core)
+            pending.push({ core: stampTokens(core, transcript?.tokens), costAtStart: state.promptOpen.costAtStart });
+        writeState(paths.stateFile, {
+            ...state,
+            promptOpen: null,
+            permissionOpen: null,
+            ...withTranscript(transcript?.transcript),
+            pending,
+        });
+        dropSettledPrompts(paths.eventsFile, events.slice(0, events.length - last.events.length));
+        return;
+    }
     // A Stop with no open prompt settles nothing: no cost, no baseline move.
     const settled = state.promptOpen ? settleCost(cost?.totalUsd, state.promptOpen.costAtStart) : {};
     const core = replayPrompt(last, { cost: settled.cost });
     if (core) {
         const assignment = await assignmentResolver(paths, deps);
-        const record = buildClaudeRecord(core, state, sessionId, cost?.model, assignment(state.cwd, sessionId));
+        const version = agentVersionOf(transcript, state);
+        const record = buildClaudeRecord(stampTokens(core, transcript?.tokens), state, sessionId, cost?.model ?? modelOf(transcript, state), assignment(state.cwd, sessionId), {
+            ...(version !== undefined ? { agentVersion: version } : {}),
+        });
         const log = deps.log ?? new JsonlWorkLog(paths.kankakuDir);
         log.append(record);
     }
@@ -146,6 +182,7 @@ async function handleStop(paths, sessionId, deps) {
         promptOpen: null,
         permissionOpen: null,
         ...(settled.baseline !== undefined ? { costBaseline: settled.baseline } : {}),
+        ...withTranscript(transcript?.transcript),
     });
     const keep = events.slice(0, events.length - last.events.length);
     dropSettledPrompts(paths.eventsFile, keep);
@@ -194,25 +231,58 @@ async function handleSessionStart(paths, sessionId, cwd, source, isStartup, ts,
 }
 async function handleSessionEnd(paths, sessionId, cwd, ts, deps) {
     const state = readState(paths.stateFile);
-    if (state?.promptOpen) {
+    if (state && (state.promptOpen || (state.pending?.length ?? 0) > 0)) {
         const { replayPrompt } = await import("./replay.js");
-        const { buildClaudeRecord } = await import("./record.js");
+        const { buildClaudeRecord, stampTokens } = await import("./record.js");
         const { JsonlWorkLog } = await import("kankaku-pi/hub");
-        const events = readEventLog(paths.eventsFile);
-        const prompts = splitPrompts(events);
-        const last = prompts[prompts.length - 1];
-        if (last) {
-            const costNow = readCost(deps.env, sessionId);
-            const settled = settleCost(costNow?.totalUsd, state.promptOpen.costAtStart);
-            const core = replayPrompt(last, { settledAt: ts, cost: settled.cost });
-            if (core) {
-                const model = costNow?.model;
-                const assignment = await assignmentResolver(paths, deps);
-                const record = buildClaudeRecord(core, state, sessionId, model, assignment(state.cwd, sessionId));
-                const log = deps.log ?? new JsonlWorkLog(paths.kankakuDir);
-                log.append(record);
+        const log = deps.log ?? new JsonlWorkLog(paths.kankakuDir);
+        const assignment = await assignmentResolver(paths, deps);
+        // Also the only place the cost-state of a headless run is visible: it is written after the last Stop.
+        const transcript = settleSafely(state, deps);
+        const version = agentVersionOf(transcript, state);
+        const headless = (state.pending?.length ?? 0) > 0 || transcript?.transcript.entrypoint === HEADLESS_ENTRYPOINT;
+        let pending = [...(state.pending ?? [])];
+        let attached = false;
+        if (state.promptOpen) {
+            const events = readEventLog(paths.eventsFile);
+            const last = splitPrompts(events).at(-1);
+            if (last) {
+                const costNow = readCost(deps.env, sessionId);
+                const settled = headless ? {} : settleCost(costNow?.totalUsd, state.promptOpen.costAtStart);
+                const core = replayPrompt(last, { settledAt: ts, cost: settled.cost });
+                if (core && headless) {
+                    pending.push({ core: stampTokens(core, transcript?.tokens), costAtStart: state.promptOpen.costAtStart });
+                    attached = true;
+                }
+                else if (core) {
+                    const record = buildClaudeRecord(stampTokens(core, transcript?.tokens), state, sessionId, costNow?.model ?? modelOf(transcript, state), assignment(state.cwd, sessionId), {
+                        ...(version !== undefined ? { agentVersion: version } : {}),
+                    });
+                    log.append(record);
+                }
             }
         }
+        if (headless && pending.length > 0) {
+            const { buildHeadlessRecords, withLateTokens } = await import("./headless.js");
+            // Lines written after the prompt settled belong to the prompt that just settled: the last one.
+            if (!attached)
+                pending = withLateTokens(pending, transcript?.tokens);
+            const model = modelOf(transcript, state);
+            const records = buildHeadlessRecords({
+                pending,
+                ...(model !== undefined ? { model } : {}),
+                state,
+                sessionId,
+                ...(transcript?.costState !== undefined ? { costState: transcript.costState } : {}),
+                assignment: assignment(state.cwd, sessionId),
+                ...(version !== undefined ? { agentVersion: version } : {}),
+            });
+            for (const record of records)
+                log.append(record);
+            // Written once, whichever path gets there first: drop the pending list before anything slow runs.
+            const { pending: _written, ...withoutPending } = state;
+            writeState(paths.stateFile, { ...withoutPending, promptOpen: null, permissionOpen: null });
+        }
     }
     try {
         await syncHeavy("session_shutdown", state?.cwd ?? cwd, deps);
@@ -275,6 +345,42 @@ async function syncHeavy(trigger, cwd, deps) {
         deps.stderr(`kankaku auto-sync: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+/** Everything that survives a state rewrite besides the fields the handler sets itself. */
+function carriedOver(state) {
+    return {
+        ...(state?.costBaseline !== undefined ? { costBaseline: state.costBaseline } : {}),
+        ...(state?.transcript !== undefined ? { transcript: state.transcript } : {}),
+        ...(state?.pending !== undefined ? { pending: state.pending } : {}),
+    };
+}
+function withTranscript(transcript) {
+    return transcript !== undefined ? { transcript } : {};
+}
+/** The transcript bookkeeping never fails a hook: on any error the state keeps what it had. */
+function trackTranscriptSafely(state, path) {
+    try {
+        return trackTranscriptAtSubmit(state?.transcript, path);
+    }
+    catch {
+        return state?.transcript;
+    }
+}
+/** Reads what the transcript gained since the stored positions; any failure means "no tokens", as before this feature. */
+function settleSafely(state, deps) {
+    try {
+        return settleTranscripts(state.transcript);
+    }
+    catch (error) {
+        deps.stderr(`kankaku: transcript: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+}
+function modelOf(settled, state) {
+    return settled?.transcript.model ?? state.transcript?.model;
+}
+function agentVersionOf(settled, state) {
+    return settled?.transcript.agentVersion ?? state.transcript?.agentVersion;
+}
 function deleteSessionFiles(paths) {
     for (const file of [paths.stateFile, paths.eventsFile, paths.targetFile]) {
         try {

package/dist/headless.js

@@ -0,0 +1,88 @@
+import { settleCost } from "./cost-chain.js";
+import { buildClaudeRecord } from "./record.js";
+/**
+ * Headless (`claude -p`, entry point `sdk-cli`) sessions have no statusline,
+ * so no per-prompt cost. Their transcript gains a `cost-state` line only
+ * after the last `Stop`, so the prompts are held as pending at `Stop` and
+ * turned into records here, at `SessionEnd` or in crash recovery. Heavy
+ * path only (imports `record.ts`).
+ */
+const MICRO = 1e6;
+/**
+ * Splits `totalUsd` over prompts in proportion to `weights`, in whole
+ * micro-dollars; the rounding remainder goes to the last share so the shares
+ * add up to the total exactly. All weights zero: equal shares. Exact for any
+ * weight size (integer arithmetic).
+ */
+export function allocateCost(totalUsd, weights) {
+    if (weights.length === 0)
+        return [];
+    const total = BigInt(Math.round(Math.max(0, totalUsd) * MICRO));
+    let parts = weights.map((weight) => BigInt(Number.isFinite(weight) && weight > 0 ? Math.round(weight) : 0));
+    if (parts.every((part) => part === 0n))
+        parts = parts.map(() => 1n);
+    const sum = parts.reduce((a, b) => a + b, 0n);
+    const shares = [];
+    let given = 0n;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const share = (total * parts[i]) / sum;
+        shares.push(share);
+        given += share;
+    }
+    shares.push(total - given);
+    return shares.map((share) => Number(share) / MICRO);
+}
+/**
+ * Adds tokens read after a prompt settled to the LAST pending prompt: the
+ * transcript is written asynchronously, so late lines belong to the prompt
+ * that just settled. No pending prompt or no tokens: unchanged.
+ */
+export function withLateTokens(pending, tokens) {
+    if (!tokens || pending.length === 0)
+        return pending;
+    const last = pending[pending.length - 1];
+    const usage = last.core.usage;
+    const merged = {
+        ...last,
+        core: {
+            ...last.core,
+            usage: {
+                ...usage,
+                input: usage.input + tokens.input,
+                output: usage.output + tokens.output,
+                cacheRead: usage.cacheRead + tokens.cacheRead,
+                cacheWrite: usage.cacheWrite + tokens.cacheWrite,
+            },
+        },
+    };
+    return [...pending.slice(0, -1), merged];
+}
+function totalTokens(prompt) {
+    const { input, output, cacheRead, cacheWrite } = prompt.core.usage;
+    return [input, output, cacheRead, cacheWrite].reduce((sum, n) => sum + (Number.isFinite(n) ? n : 0), 0);
+}
+/**
+ * The records of a finished headless session. The session cost is the
+ * `cost-state` total put through the chained baseline (`settleCost`, from the
+ * first pending prompt's start); with several prompts it is shared by their
+ * token totals and every record is marked `costAllocated`. Without a usable
+ * `cost-state` (none, or one that flags a model with unknown pricing) the
+ * records carry no cost, exactly as a session without a statusline does.
+ */
+export function buildHeadlessRecords(input) {
+    const { pending, state, sessionId } = input;
+    if (pending.length === 0)
+        return [];
+    const usable = input.costState !== undefined && !input.costState.hasUnknownModelCost;
+    const sessionCost = usable ? settleCost(input.costState.totalUsd, pending[0].costAtStart).cost : undefined;
+    const allocated = pending.length > 1;
+    const costs = sessionCost === undefined ? undefined : allocated ? allocateCost(sessionCost, pending.map(totalTokens)) : [sessionCost];
+    return pending.map((prompt, index) => {
+        const cost = costs?.[index];
+        const core = cost === undefined ? prompt.core : { ...prompt.core, usage: { ...prompt.core.usage, cost }, costObserved: true };
+        return buildClaudeRecord(core, state, sessionId, input.model, input.assignment, {
+            ...(input.agentVersion !== undefined ? { agentVersion: input.agentVersion } : {}),
+            ...(cost !== undefined && allocated ? { costAllocated: true } : {}),
+        });
+    });
+}

package/dist/inflight-recovery.js

@@ -4,7 +4,9 @@ import { listStateFiles, resolveTargetFile } from "./paths.js";
 import { readState } from "./session-state.js";
 import { readEventLog } from "./event-log.js";
 import { splitPrompts, replayPrompt } from "./replay.js";
-import { buildClaudeRecord } from "./record.js";
+import { buildClaudeRecord, stampTokens } from "./record.js";
+import { settleTranscripts } from "./transcript-settle.js";
+import { buildHeadlessRecords, withLateTokens } from "./headless.js";
 import { readCost, deleteCost } from "./cost-store.js";
 import { settleCost } from "./cost-chain.js";
 /**
@@ -37,23 +39,52 @@ export function recoverStaleSessions(input) {
         const dead = state.pid <= 0 || !input.isAlive(state.pid);
         if (!dead)
             continue;
-        if (state.promptOpen && state.cwd !== "") {
-            const events = readEventLog(eventsFile);
-            const prompts = splitPrompts(events);
-            const last = prompts[prompts.length - 1];
-            if (last && last.open) {
-                // Close at the prompt's last recorded activity, never at recovery
-                // time (which is the next session start, possibly hours later).
-                // `now` is only a fallback when no usable timestamp exists.
-                const lastTs = last.events[last.events.length - 1]?.ts;
-                const settledAt = typeof lastTs === "number" && Number.isFinite(lastTs) ? lastTs : input.now;
-                const costNow = readCost(input.env, sessionId);
-                const core = replayPrompt(last, { settledAt, cost: settleCost(costNow?.totalUsd, state.promptOpen.costAtStart).cost });
-                if (core) {
-                    const model = costNow?.model;
-                    records.push(buildClaudeRecord(core, state, sessionId, model, input.resolveAssignment?.(state.cwd, sessionId)));
+        const held = [...(state.pending ?? [])];
+        const openPrompt = state.promptOpen && state.cwd !== "" ? state.promptOpen : undefined;
+        if (openPrompt || held.length > 0) {
+            // One read of the dead session's transcript: tokens of the open prompt,
+            // the entry point, and the cost-state a headless run wrote after its last Stop.
+            const transcript = settleSafely(state);
+            const version = transcript?.transcript.agentVersion ?? state.transcript?.agentVersion;
+            const headless = held.length > 0 || transcript?.transcript.entrypoint === "sdk-cli";
+            const costNow = readCost(input.env, sessionId);
+            const model = costNow?.model ?? transcript?.transcript.model ?? state.transcript?.model;
+            let attached = false;
+            const headlessModel = transcript?.transcript.model ?? state.transcript?.model;
+            const assignment = input.resolveAssignment?.(state.cwd, sessionId);
+            if (openPrompt) {
+                const events = readEventLog(eventsFile);
+                const prompts = splitPrompts(events);
+                const last = prompts[prompts.length - 1];
+                if (last && last.open) {
+                    // Close at the prompt's last recorded activity, never at recovery
+                    // time (which is the next session start, possibly hours later).
+                    // `now` is only a fallback when no usable timestamp exists.
+                    const lastTs = last.events[last.events.length - 1]?.ts;
+                    const settledAt = typeof lastTs === "number" && Number.isFinite(lastTs) ? lastTs : input.now;
+                    const cost = headless ? undefined : settleCost(costNow?.totalUsd, openPrompt.costAtStart).cost;
+                    const core = replayPrompt(last, { settledAt, cost });
+                    if (core && headless) {
+                        held.push({ core: stampTokens(core, transcript?.tokens), costAtStart: openPrompt.costAtStart });
+                        attached = true;
+                    }
+                    else if (core) {
+                        records.push(buildClaudeRecord(stampTokens(core, transcript?.tokens), state, sessionId, model, assignment, {
+                            ...(version !== undefined ? { agentVersion: version } : {}),
+                        }));
+                    }
                 }
             }
+            records.push(...buildHeadlessRecords({
+                // The file is final: lines written after the last prompt settled belong to the last pending one.
+                pending: attached ? held : withLateTokens(held, transcript?.tokens),
+                state,
+                sessionId,
+                ...(headlessModel !== undefined ? { model: headlessModel } : {}),
+                ...(transcript?.costState !== undefined ? { costState: transcript.costState } : {}),
+                ...(assignment !== undefined ? { assignment } : {}),
+                ...(version !== undefined ? { agentVersion: version } : {}),
+            }));
         }
         safeUnlink(stateFile);
         safeUnlink(eventsFile);
@@ -62,6 +93,15 @@ export function recoverStaleSessions(input) {
     }
     return records;
 }
+/** A dead session's transcript is best-effort: any failure means a record without tokens, as before. */
+function settleSafely(state) {
+    try {
+        return settleTranscripts(state.transcript);
+    }
+    catch {
+        return undefined;
+    }
+}
 function sessionIdFromStateFile(file) {
     const match = basename(file).match(/^(.*)\.state\.json$/);
     return match?.[1];

package/dist/record.js

@@ -13,6 +13,16 @@ export function readPackageVersion(file) {
 }
 // Resolved once per hook process; `src/` and `dist/` share the same depth.
 const PLUGIN_VERSION = readPackageVersion(join(dirname(dirname(fileURLToPath(import.meta.url))), "package.json"));
+/**
+ * Stamps the four token counts read from the transcript onto a replayed
+ * record. The cost stays as the replay set it; without tokens the record is
+ * returned as it is.
+ */
+export function stampTokens(core, tokens) {
+    if (!tokens)
+        return core;
+    return { ...core, usage: { ...core.usage, input: tokens.input, output: tokens.output, cacheRead: tokens.cacheRead, cacheWrite: tokens.cacheWrite } };
+}
 /**
  * Attaches the orchestrator metadata a replayed {@link WorkRecordCore}
  * needs to become a persistable {@link WorkRecord}. `assignment` carries the
@@ -25,11 +35,11 @@ const PLUGIN_VERSION = readPackageVersion(join(dirname(dirname(fileURLToPath(imp
  *
  * Also stamps who MEASURED the record (`agent`, `plugin`, `pluginVersion`),
  * so a worklog later synced by another tool (the `kankaku` CLI) keeps the
- * right identity. `agentVersion` is omitted: Claude Code passes its version
- * to no hook payload, and spawning `claude --version` from a hook is not
- * acceptable.
+ * right identity. `agentVersion` is stamped only when `extras` carries one,
+ * read from the session transcript (no hook payload carries it, and
+ * spawning `claude --version` from a hook is not acceptable); never guessed.
  */
-export function buildClaudeRecord(core, state, sessionId, model, assignment = {}) {
+export function buildClaudeRecord(core, state, sessionId, model, assignment = {}, extras = {}) {
     const { target, legacyClient } = assignment;
     return {
         ...core,
@@ -42,6 +52,8 @@ export function buildClaudeRecord(core, state, sessionId, model, assignment = {}
         agent: "claude-code",
         plugin: "kankaku-claude",
         ...(PLUGIN_VERSION !== undefined ? { pluginVersion: PLUGIN_VERSION } : {}),
+        ...(extras.agentVersion !== undefined ? { agentVersion: extras.agentVersion } : {}),
+        ...(extras.costAllocated === true ? { costAllocated: true } : {}),
         ...(model ? { model: `anthropic/${model}` } : {}),
         ...(legacyClient !== undefined ? { client: legacyClient } : {}),
         ...(target !== undefined

package/dist/session-state.js

@@ -32,7 +32,54 @@ export function readState(file) {
     catch {
         return undefined;
     }
-    return isSessionState(parsed) ? parsed : undefined;
+    return isSessionState(parsed) ? withoutInvalidOptionals(parsed) : undefined;
+}
+/** The optional transcript fields are advisory: a malformed one is dropped, never the whole state. */
+function withoutInvalidOptionals(state) {
+    const { transcript, pending, ...rest } = state;
+    return {
+        ...rest,
+        ...(isTranscriptState(transcript) ? { transcript } : {}),
+        ...(Array.isArray(pending) && pending.every(isPendingPrompt) ? { pending } : {}),
+    };
+}
+function isTranscriptState(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const o = value;
+    if (typeof o.path !== "string" || typeof o.offsets !== "object" || o.offsets === null)
+        return false;
+    if (o.agentVersion !== undefined && typeof o.agentVersion !== "string")
+        return false;
+    if (o.entrypoint !== undefined && typeof o.entrypoint !== "string")
+        return false;
+    if (o.model !== undefined && typeof o.model !== "string")
+        return false;
+    return Object.values(o.offsets).every((position) => {
+        if (typeof position !== "object" || position === null)
+            return false;
+        const p = position;
+        return (typeof p.bytes === "number" &&
+            Number.isFinite(p.bytes) &&
+            p.bytes >= 0 &&
+            (p.lastMessageId === undefined || typeof p.lastMessageId === "string") &&
+            (p.lastMessageUsage === undefined || isTokenUsage(p.lastMessageUsage)));
+    });
+}
+function isTokenUsage(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const u = value;
+    return ["input", "output", "cacheRead", "cacheWrite"].every((key) => typeof u[key] === "number" && Number.isFinite(u[key]) && u[key] >= 0);
+}
+function isPendingPrompt(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const o = value;
+    return (typeof o.core === "object" &&
+        o.core !== null &&
+        typeof o.core.id === "string" &&
+        (o.costAtStart === undefined || o.costAtStart === null || typeof o.costAtStart === "number"));
 }
 /** Atomic tmp+rename write, creating parent directories as needed. */
 export function writeState(file, state) {

package/dist/transcript-settle.js

@@ -0,0 +1,147 @@
+import { MAX_SETTLE_BYTES, listSubagentTranscripts, readTranscriptHead, readTranscriptSince, statTranscriptSize, } from "./transcript.js";
+/**
+ * Session-level use of the transcript reader: which files belong to a
+ * session, where each one is read from, and what a settle learns from them.
+ * Node builtins only (see `transcript.ts`).
+ */
+/**
+ * `UserPromptSubmit`: remember the transcript path and, when no position is
+ * known yet, the CURRENT size of the main file and of every subagent file,
+ * so a session that existed before the plugin (or was resumed) does not
+ * read its history at the first settle. Metadata only: no file is read. A
+ * new path (the session moved to another file) restarts the positions.
+ */
+export function trackTranscriptAtSubmit(existing, path) {
+    if (path === undefined || path === "")
+        return existing;
+    if (existing && existing.path === path && Object.keys(existing.offsets).length > 0)
+        return existing;
+    const offsets = {};
+    for (const file of [path, ...listSubagentTranscripts(path)]) {
+        const size = statTranscriptSize(file);
+        if (size !== undefined)
+            offsets[file] = { bytes: size };
+    }
+    return {
+        path,
+        offsets,
+        ...(existing?.agentVersion !== undefined ? { agentVersion: existing.agentVersion } : {}),
+        ...(existing?.entrypoint !== undefined ? { entrypoint: existing.entrypoint } : {}),
+        ...(existing?.model !== undefined ? { model: existing.model } : {}),
+    };
+}
+/** Poll every 25 ms; not before 100 ms and not after 300 ms since the hook started (see {@link waitForTranscript}). */
+export const TRANSCRIPT_POLL_MS = 25;
+export const TRANSCRIPT_WAIT_MIN_MS = 100;
+export const TRANSCRIPT_WAIT_MAX_MS = 300;
+/**
+ * Claude Code writes the transcript asynchronously: the last assistant lines
+ * reach the disk shortly AFTER the Stop hook has started, while earlier
+ * assistant messages of the same prompt are usually on disk long before. So
+ * a line being there is not enough. Before a settle reads, poll the main
+ * transcript every {@link TRANSCRIPT_POLL_MS} until ALL hold: at least
+ * {@link TRANSCRIPT_WAIT_MIN_MS} have passed since `startedAt` (when the hook
+ * process started), its size did not change across two consecutive polls,
+ * and its new bytes hold a complete assistant line. It gives up
+ * {@link TRANSCRIPT_WAIT_MAX_MS} after `startedAt` regardless; time already
+ * spent (the statusline wait) counts, so a hook that waited 300 ms or more
+ * does not sleep again. The caller then reads whatever is there. Clock and
+ * sleep are injected. Never throws.
+ */
+export async function waitForTranscript(transcript, clock, startedAt = clock.now()) {
+    if (!transcript)
+        return;
+    const position = transcript.offsets[transcript.path] ?? { bytes: 0 };
+    let previousSize;
+    for (;;) {
+        const elapsed = clock.now() - startedAt;
+        if (elapsed >= TRANSCRIPT_WAIT_MAX_MS)
+            return;
+        let ready = false;
+        try {
+            const size = statTranscriptSize(transcript.path);
+            const read = readTranscriptSince(transcript.path, position);
+            const sawLine = read.lastMessageId !== undefined &&
+                (read.lastMessageId !== position.lastMessageId || read.usage.input + read.usage.output + read.usage.cacheRead + read.usage.cacheWrite > 0);
+            ready = elapsed >= TRANSCRIPT_WAIT_MIN_MS && sawLine && size !== undefined && size === previousSize;
+            previousSize = size;
+        }
+        catch {
+            return;
+        }
+        if (ready)
+            return;
+        await clock.sleep(Math.min(TRANSCRIPT_POLL_MS, TRANSCRIPT_WAIT_MAX_MS - elapsed));
+    }
+}
+/**
+ * Settle: read everything appended since the stored positions, in the main
+ * transcript and in every subagent file (a file without a position starts
+ * at 0), sum it, and return the advanced positions. At most
+ * `maxBytes` (default {@link MAX_SETTLE_BYTES}) are read across all files;
+ * a file whose new content does not fit is skipped to its end without
+ * counting and the whole result carries no tokens.
+ */
+export function settleTranscripts(transcript, options = {}) {
+    if (!transcript)
+        return undefined;
+    let remaining = options.maxBytes ?? MAX_SETTLE_BYTES;
+    const offsets = { ...transcript.offsets };
+    const total = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+    let truncated = false;
+    let version;
+    let entrypoint;
+    let mainModel;
+    let subagentModel;
+    let costState;
+    const files = [transcript.path, ...listSubagentTranscripts(transcript.path)];
+    for (const file of files) {
+        const before = offsets[file] ?? { bytes: 0 };
+        const result = readTranscriptSince(file, before, { maxBytes: remaining });
+        if (result.truncated) {
+            truncated = true;
+            remaining = 0;
+        }
+        else {
+            const start = result.position.bytes >= before.bytes ? before.bytes : 0;
+            remaining = Math.max(0, remaining - (result.position.bytes - start));
+        }
+        if (file in offsets || result.position.bytes > 0)
+            offsets[file] = result.position;
+        total.input += result.usage.input;
+        total.output += result.usage.output;
+        total.cacheRead += result.usage.cacheRead;
+        total.cacheWrite += result.usage.cacheWrite;
+        if (version === undefined)
+            version = result.version;
+        if (entrypoint === undefined)
+            entrypoint = result.entrypoint;
+        if (file === transcript.path) {
+            costState = result.costState;
+            mainModel = result.model;
+        }
+        else if (result.model !== undefined) {
+            subagentModel = result.model;
+        }
+    }
+    if ((version ?? transcript.agentVersion) === undefined || (entrypoint ?? transcript.entrypoint) === undefined) {
+        const head = readTranscriptHead(transcript.path);
+        version ??= head.version;
+        entrypoint ??= head.entrypoint;
+    }
+    const agentVersion = version ?? transcript.agentVersion;
+    const knownEntrypoint = entrypoint ?? transcript.entrypoint;
+    const model = mainModel ?? transcript.model ?? subagentModel;
+    return {
+        tokens: truncated ? undefined : total,
+        transcript: {
+            path: transcript.path,
+            offsets,
+            ...(agentVersion !== undefined ? { agentVersion } : {}),
+            ...(knownEntrypoint !== undefined ? { entrypoint: knownEntrypoint } : {}),
+            ...(model !== undefined ? { model } : {}),
+        },
+        ...(costState !== undefined ? { costState } : {}),
+        truncated,
+    };
+}

package/dist/transcript.js

@@ -0,0 +1,286 @@
+import { closeSync, openSync, readSync, readdirSync, fstatSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+/**
+ * Reader for Claude Code's session transcripts (`~/.claude/projects/...jsonl`).
+ *
+ * The format is internal and undocumented and may change with any Claude
+ * Code release, so everything here is tolerant: a missing file, an
+ * unparseable line or an unexpected field yields zero / `undefined`, never
+ * an error. Only numbers, the Claude Code version, the entry point and the
+ * session cost total are ever taken from a line; no message content is
+ * kept. Node builtins only, so it may sit on the light hook path (which
+ * only ever uses {@link statTranscriptSize} and {@link listSubagentTranscripts}).
+ */
+/** Most bytes read across all transcript files of one settle (16 MiB). */
+export const MAX_SETTLE_BYTES = 16 * 1024 * 1024;
+export function zeroUsage() {
+    return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+}
+/** Lines that can matter besides the first few (which are tried for the version and entry point). */
+const RELEVANT_LINE = /"type"\s*:\s*"(?:assistant|cost-state)"/;
+const METADATA_LINES = 20;
+function counted(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseUsage(raw) {
+    return {
+        input: counted(raw.input_tokens),
+        output: counted(raw.output_tokens),
+        cacheRead: counted(raw.cache_read_input_tokens),
+        cacheWrite: counted(raw.cache_creation_input_tokens),
+    };
+}
+/**
+ * Pure: parses the text of complete transcript lines.
+ *
+ * - Claude Code writes one message over several adjacent lines whose usage
+ *   grows (earlier lines are partial snapshots), so an `assistant` message is
+ *   counted once per `message.id` by its LAST line in the chunk. A line
+ *   without an id cannot be de-duplicated and is not counted.
+ * - A message can straddle two reads. `previous` carries the last id and the
+ *   usage counted for it: when this chunk holds more lines of that id, only
+ *   the growth is added, per field and never negative. A `previous` with an
+ *   id but no usage (a legacy position) skips that id's lines instead.
+ * - A non-finite, negative or non-numeric usage field counts as 0.
+ * - `version` and `entrypoint` come from the first line that carries each.
+ * - `costState` is the last valid `cost-state` line.
+ */
+export function parseTranscriptChunk(text, previous) {
+    const finals = new Map();
+    let lastMessageId = previous.lastMessageId;
+    let version;
+    let entrypoint;
+    let model;
+    let costState;
+    let index = 0;
+    for (const line of text.split("\n")) {
+        const lineNumber = index++;
+        if (line.trim() === "")
+            continue;
+        const needsMetadata = (version === undefined || entrypoint === undefined) && lineNumber < METADATA_LINES;
+        if (!needsMetadata && !RELEVANT_LINE.test(line))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isObject(parsed))
+            continue;
+        if (version === undefined && typeof parsed.version === "string" && parsed.version !== "")
+            version = parsed.version;
+        if (entrypoint === undefined && typeof parsed.entrypoint === "string" && parsed.entrypoint !== "")
+            entrypoint = parsed.entrypoint;
+        if (parsed.type === "assistant") {
+            const message = parsed.message;
+            if (isObject(message) && typeof message.model === "string" && message.model !== "")
+                model = message.model;
+            if (!isObject(message) || typeof message.id !== "string" || message.id === "")
+                continue;
+            lastMessageId = message.id;
+            if (isObject(message.usage))
+                finals.set(message.id, parseUsage(message.usage));
+            else if (!finals.has(message.id))
+                finals.set(message.id, zeroUsage());
+        }
+        else if (parsed.type === "cost-state") {
+            const total = parsed.totalCostUSD;
+            if (typeof total !== "number" || !Number.isFinite(total) || total < 0)
+                continue;
+            costState = { totalUsd: total, hasUnknownModelCost: parsed.hasUnknownModelCost === true };
+        }
+    }
+    const usage = zeroUsage();
+    for (const [id, final] of finals) {
+        let added = final;
+        if (id === previous.lastMessageId) {
+            const before = previous.lastMessageUsage;
+            if (before === undefined)
+                continue; // legacy: this message's total so far is unknown, skip it
+            added = {
+                input: Math.max(0, final.input - before.input),
+                output: Math.max(0, final.output - before.output),
+                cacheRead: Math.max(0, final.cacheRead - before.cacheRead),
+                cacheWrite: Math.max(0, final.cacheWrite - before.cacheWrite),
+            };
+        }
+        usage.input += added.input;
+        usage.output += added.output;
+        usage.cacheRead += added.cacheRead;
+        usage.cacheWrite += added.cacheWrite;
+    }
+    let lastMessageUsage = previous.lastMessageUsage;
+    if (lastMessageId !== undefined && finals.has(lastMessageId)) {
+        const final = finals.get(lastMessageId);
+        if (lastMessageId !== previous.lastMessageId)
+            lastMessageUsage = final;
+        else if (previous.lastMessageUsage !== undefined) {
+            const before = previous.lastMessageUsage;
+            lastMessageUsage = {
+                input: Math.max(before.input, final.input),
+                output: Math.max(before.output, final.output),
+                cacheRead: Math.max(before.cacheRead, final.cacheRead),
+                cacheWrite: Math.max(before.cacheWrite, final.cacheWrite),
+            };
+        }
+    }
+    return {
+        usage,
+        ...(lastMessageId !== undefined ? { lastMessageId } : {}),
+        ...(lastMessageUsage !== undefined ? { lastMessageUsage } : {}),
+        ...(version !== undefined ? { version } : {}),
+        ...(entrypoint !== undefined ? { entrypoint } : {}),
+        ...(model !== undefined ? { model } : {}),
+        ...(costState !== undefined ? { costState } : {}),
+    };
+}
+/**
+ * Reads the complete lines after `position.bytes` and parses them.
+ *
+ * - A trailing partial line (no newline yet) is not consumed: the returned
+ *   position stops before it.
+ * - A file shorter than the stored position was rotated or replaced: it is
+ *   read from 0 and the stale `lastMessageId` is dropped.
+ * - More than `maxBytes` of new content (default {@link MAX_SETTLE_BYTES}) is
+ *   not read at all: the position jumps to the end of the file, nothing is
+ *   counted and `truncated` is set, so a hook never times out on a huge file.
+ * - A missing or unreadable file returns zero usage and the same position.
+ */
+export function readTranscriptSince(file, position, options = {}) {
+    const unchanged = { usage: zeroUsage(), position, truncated: false };
+    const maxBytes = options.maxBytes ?? MAX_SETTLE_BYTES;
+    let fd;
+    try {
+        fd = openSync(file, "r");
+    }
+    catch {
+        return unchanged;
+    }
+    try {
+        const stats = fstatSync(fd);
+        if (!stats.isFile())
+            return unchanged;
+        const size = stats.size;
+        const replaced = size < position.bytes;
+        const start = replaced ? 0 : position.bytes;
+        const lastMessageId = replaced ? undefined : position.lastMessageId;
+        const lastMessageUsage = replaced ? undefined : position.lastMessageUsage;
+        const carried = { ...(lastMessageId !== undefined ? { lastMessageId } : {}), ...(lastMessageUsage !== undefined ? { lastMessageUsage } : {}) };
+        const length = size - start;
+        if (length === 0) {
+            return { usage: zeroUsage(), position: { bytes: start, ...carried }, truncated: false };
+        }
+        if (length > maxBytes) {
+            return {
+                usage: zeroUsage(),
+                position: { bytes: size, ...carried },
+                truncated: true,
+            };
+        }
+        const buffer = Buffer.alloc(length);
+        let filled = 0;
+        while (filled < length) {
+            const n = readSync(fd, buffer, filled, length - filled, start + filled);
+            if (n === 0)
+                break;
+            filled += n;
+        }
+        const lastNewline = buffer.subarray(0, filled).lastIndexOf(0x0a);
+        if (lastNewline < 0) {
+            return { usage: zeroUsage(), position: { bytes: start, ...carried }, truncated: false };
+        }
+        const consumed = lastNewline + 1;
+        const parsed = parseTranscriptChunk(buffer.subarray(0, consumed).toString("utf8"), carried);
+        return {
+            ...parsed,
+            position: {
+                bytes: start + consumed,
+                ...(parsed.lastMessageId !== undefined ? { lastMessageId: parsed.lastMessageId } : {}),
+                ...(parsed.lastMessageUsage !== undefined ? { lastMessageUsage: parsed.lastMessageUsage } : {}),
+            },
+            truncated: false,
+        };
+    }
+    catch {
+        return unchanged;
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch {
+            // nothing to do
+        }
+    }
+}
+/** How much of the start of a transcript is looked at for the version and entry point (64 KiB). */
+const HEAD_BYTES = 64 * 1024;
+/**
+ * The version and entry point from the first complete lines of a transcript.
+ * A settle needs them even when no new line carries them yet (the transcript
+ * is written asynchronously and the read position is already past the first
+ * lines). Bounded; empty on any problem.
+ */
+export function readTranscriptHead(file) {
+    let fd;
+    try {
+        fd = openSync(file, "r");
+    }
+    catch {
+        return {};
+    }
+    try {
+        const buffer = Buffer.alloc(HEAD_BYTES);
+        const n = readSync(fd, buffer, 0, HEAD_BYTES, 0);
+        const lastNewline = buffer.subarray(0, n).lastIndexOf(0x0a);
+        if (lastNewline < 0)
+            return {};
+        const { version, entrypoint } = parseTranscriptChunk(buffer.subarray(0, lastNewline + 1).toString("utf8"), {});
+        return { ...(version !== undefined ? { version } : {}), ...(entrypoint !== undefined ? { entrypoint } : {}) };
+    }
+    catch {
+        return {};
+    }
+    finally {
+        try {
+            closeSync(fd);
+        }
+        catch {
+            // nothing to do
+        }
+    }
+}
+/** Current size of a file in bytes (metadata only, no read), or `undefined` when it cannot be statted. */
+export function statTranscriptSize(file) {
+    try {
+        const stats = statSync(file);
+        return stats.isFile() ? stats.size : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The subagent transcripts of a session: `*.jsonl` files in
+ * `<dirname>/<session id>/subagents/`, sorted, everything else ignored.
+ * Empty when the directory does not exist.
+ */
+export function listSubagentTranscripts(sessionTranscriptPath) {
+    const dir = join(dirname(sessionTranscriptPath), basename(sessionTranscriptPath, ".jsonl"), "subagents");
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+        .map((entry) => join(dir, entry.name))
+        .sort();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kankaku-claude",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Claude Code plugin that records how long the agent works on each user prompt, in kankaku's worklog format.",
   "type": "module",
   "files": [
@@ -27,7 +27,7 @@
     "prepublishOnly": "npm run check"
   },
   "dependencies": {
-    "kankaku-pi": "^1.2.0"
+    "kankaku-pi": "^1.3.0"
   },
   "devDependencies": {
     "@types/node": "^24.13.4",