kankaku-claude 0.10.0 → 0.12.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": "0.10.0",
+  "version": "0.12.0",
   "author": {
     "name": "soyunninja"
   },

package/CHANGELOG.md

@@ -4,6 +4,59 @@ 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/).
 
+## 0.12.0 — 2026-09-29
+
+### Added
+
+- **`/kankaku:task` links the session to a hub task.** It lists the open
+  tasks of the project resolved for the folder, and picks one by number, hub
+  id or title text (`clear` removes the link). The link is session-only, kept
+  in `<KANKAKU_DIR>/claude/<session>.target.json`, and the records written at
+  Stop, SessionEnd and crash recovery carry `hubTaskId` and `hubTaskTitle`
+  while the task still belongs to the resolved project. `/kankaku:status` and
+  `/kankaku:doctor` print the `task:` line. The CLI finds its session from its
+  own process; `KANKAKU_CLAUDE_SESSION` names it explicitly.
+
+## 0.11.0 — 2026-09-29
+
+### Added
+
+- **Records resolve their client and project automatically.** Records
+  written at Stop, SessionEnd and crash recovery now carry `clientId`,
+  `clientName`, `projectId` and `projectName` (and the legacy `client`
+  label) when the project `config.json` ids or the cached catalog's
+  `repo_paths` match the session's working directory, so the hub no longer
+  files them under the unassigned client. The catalog is read from
+  `~/.kankaku/catalog.json` only: no network, no delay, and no target when
+  the cache is missing. Records already on disk are not rewritten, and rows
+  already uploaded as unassigned stay so until reassigned in the web app.
+- `/kankaku:status` and `/kankaku:doctor` print the resolved target and its
+  source, or `target: none (<reason>)`.
+
+## 0.10.2 — 2026-09-29
+
+### Fixed
+
+- **Records synced by another tool were attributed to the syncer.** Records
+  carried no `agent`/`plugin`, so when the kankaku TUI synced a worklog
+  written by Claude Code, the hub row was created as agent `unknown`,
+  plugin `kankaku-tui`. Every record (settled, settled at SessionEnd, or
+  recovered as `interrupted`) now carries `agent: "claude-code"`,
+  `plugin: "kankaku-claude"` and `pluginVersion`. Records already on disk
+  are not rewritten.
+
+## 0.10.1 — 2026-09-29
+
+### Fixed
+
+- **A prompt interrupted by a hung session was recorded with the time until
+  the next session started.** Crash recovery settled the open prompt at
+  recovery time, so a session that hung and was recovered the next morning
+  produced a record with a 14.4 h wall time. The prompt is now closed at
+  the timestamp of the last event recorded for it (its own
+  `UserPromptSubmit` when nothing followed); a waiting span still open is
+  closed at the same instant, and the record stays `interrupted`.
+
 ## 0.10.0 — 2026-09-28
 
 ### Fixed

package/README.md

@@ -25,6 +25,13 @@ its own `worklog.jsonl`. This means kankaku's existing report and export
 tooling can read this plugin's worklog unchanged. kankaku-claude also exposes
 manual and best-effort automatic hub sync through kankaku's public hub adapters (below).
 
+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.
+
 ## Requirements
 
 - Claude Code with plugin support.
@@ -58,8 +65,7 @@ README ("Claude Code") for the full behaviour, the
 `--claude-plugin-dir`/`KANKAKU_CLAUDE_PLUGIN_DIR` override, and why you
 should drop `--plugin-dir` (below) once this has run.
 
-**Manual/dev: `--plugin-dir` (also required for the `/kankaku:*` slash
-commands).** Clone this repository, build it once, then point Claude Code
+**Manual/dev: `--plugin-dir`.** Clone this repository, build it once, then point Claude Code
 at it directly:
 
 ```bash
@@ -79,10 +85,10 @@ new commits.
 If your Claude Code version does not recognize `--plugin-dir`, or plugin
 loading has changed since this was written, check your installed version's
 own plugin documentation (`claude --help`, or `/plugin` inside a session) for
-the current local-install flow. `--plugin-dir` is also the only way to get
-the `/kankaku:*` slash commands (`/kankaku:report`, `/kankaku:setup`, …),
-since a Claude Code plugin loaded only through settings.json hooks — the
-recommended path above — never registers commands.
+the current local-install flow. A plugin
+wired only through settings.json hooks does not register its commands, so
+`kankaku setup` installs the `/kankaku:*` commands separately (see
+"Commands").
 
 **Do not combine the two.** If `kankaku setup` has already configured this
 machine's `~/.claude/settings.json` hooks, loading the plugin again with
@@ -127,11 +133,17 @@ anything behind in whatever project happens to be open.
 
 ## Commands
 
+`kankaku setup` installs these as user commands under
+`~/.claude/commands/kankaku/`, so they work without `--plugin-dir`.
+
 - `/kankaku:report` — a report of recent work, grouped by day (wraps
   `node dist/cli.js report`).
 - `/kankaku:status` — the sessions kankaku-claude currently has state for:
   session id, whether its process is still alive, whether a prompt is open,
-  and the last cost the statusline reported (wraps `node dist/cli.js status`).
+  and the last cost the statusline reported, preceded by the resolved work
+  target (wraps `node dist/cli.js status`).
+- `/kankaku:task` — links this session to a hub task (wraps
+  `node dist/cli.js task`); see "Linking a task" below.
 - `/kankaku:setup` — prints the `statusLine` snippet described above (wraps
   `node dist/cli.js setup`).
 - `/kankaku:sync` — manually syncs recent local work records to the hub
@@ -186,6 +198,65 @@ window, and record settings above apply to both manual and automatic sync.
 Automatic runs use kankaku's change detection and per-prompt throttle; session
 boundaries are not throttled. Set `KANKAKU_SYNC_AUTO=0` to opt out.
 
+### Client and project assignment
+
+Each record is stamped with a hub client and project when one resolves, so
+the hub files the task under the right client instead of "Sin determinar".
+Sources, in order:
+
+1. the project's `<KANKAKU_DIR>/config.json` ids (`clientId`, optional
+   `projectId`);
+2. the cached catalog's `repo_paths`: the active project whose path equals
+   the session's working directory, or contains it.
+
+Inactive clients and projects, and the "unassigned" client, are never used.
+The catalog is read from the cache file `~/.kankaku/catalog.json` only; a
+hook never fetches it and never waits on the network. Every real sync
+refreshes that cache, and `kankaku catalog refresh` refreshes it on demand.
+Without a readable cache (or without hub credentials, which name the hub the
+cache belongs to) no target resolves and records stay unassigned, exactly as
+before. The legacy `client` label is the client's code when it is a valid
+label; without a hub target it comes from `KANKAKU_CLIENT`, then the
+`client` in `config.json`.
+
+The target is resolved when a record is written (`Stop`, `SessionEnd`,
+crash recovery), never on the per-tool-call hooks. `/kankaku:status` and
+`/kankaku:doctor` print `target: <client> · <project> (source: ...)`, or
+`target: none (<reason>)`.
+
+### Linking a task
+
+`/kankaku:task` links the session to one hub task of the project resolved
+for the folder, so the records written from then on carry that task:
+
+- `/kankaku:task` lists the project's open tasks (status `open` or `doing`),
+  numbered, and marks the linked one; Claude then asks which one you want.
+- `/kankaku:task <number>` picks from the last list shown in this session,
+  `/kankaku:task <id>` by hub id, and `/kankaku:task <text>` by a unique
+  case-insensitive part of the title (several matches are listed and nothing
+  changes). A purely numeric argument is always a list number.
+- `/kankaku:task clear` removes the link.
+
+The link is session-only, like `/kankaku task pick` in pi: it is stored in
+`<KANKAKU_DIR>/claude/<session>.target.json`, never in `config.json`, and is
+removed when the session ends. The list refreshes the catalog first (bounded
+to 3 seconds) and falls back to the cache, saying how old it is; the hooks
+still only read the cache. A record keeps the link only while the task still
+belongs to the resolved project in the catalog; otherwise it is dropped and
+`/kankaku:status` and `/kankaku:doctor` print
+`task: none (linked task "<title>" is not in project <name>)`. Both print
+`task: <title>` or `task: none` otherwise.
+
+The CLI finds its session from its own process: it walks up to the Claude
+Code process and takes the session state of this project whose `pid` matches
+(most recent activity first). Without a session it prints
+`no active Claude Code session found for this folder`. Set
+`KANKAKU_CLAUDE_SESSION=<session id>` to name the session explicitly (tests,
+scripting); it wins over the process lookup. Overriding the client or project
+from Claude Code is not supported yet. Assignment is create-only
+on the hub: a row already uploaded as unassigned stays that way until it is
+reassigned in the web app; a later sync does not move it.
+
 ## Where the files live
 
 - `<KANKAKU_DIR>/worklog.jsonl` — the append-only log of settled records,
@@ -218,6 +289,12 @@ 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`.
 
+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
+followed — never at the moment of recovery, so a session that hung and was
+recovered hours later does not report those hours as work. A waiting span
+still open is closed at that same instant.
+
 ## Limitations
 
 - **`turns` is always 1 per run.** Claude Code hooks give no way to observe

package/commands/task.md

@@ -0,0 +1,14 @@
+---
+description: Link this session to a hub task (list open tasks, pick one, or clear the link)
+argument-hint: [number | id | text | clear]
+allowed-tools: Bash(node:*)
+---
+
+Run the kankaku CLI task command and show its output to the user verbatim,
+inside a code block, with no summarizing or reformatting:
+
+!node "${CLAUDE_PLUGIN_ROOT}/dist/cli.js" task $ARGUMENTS
+
+If no argument was given and the output lists tasks, ask the user which one
+they want (by number), then run the same CLI command with that number and show
+its output verbatim in a code block. Never pick a task on the user's behalf.

package/dist/cli-core.js

@@ -6,7 +6,9 @@ import { readCost } from "./cost-store.js";
 import { formatReport } from "./report.js";
 import { runSyncCli } from "./sync-cli.js";
 import { runDoctor } from "./doctor.js";
-const USAGE = "usage: node dist/cli.js <report|status|setup|sync|doctor> [--days N]\n";
+import { runTaskCli } from "./task-cli.js";
+import { formatTargetLine, formatTaskLine, resolveSessionWorkTarget } from "./work-target.js";
+const USAGE = "usage: node dist/cli.js <report|status|setup|sync|doctor|task> [--days N]\n";
 /** CLI commands, resolved from `deps.cwd`. */
 export async function runCli(argv, deps) {
     const [command, ...rest] = argv;
@@ -19,6 +21,8 @@ export async function runCli(argv, deps) {
             return runSetup(deps);
         case "sync":
             return runSyncCli(rest, deps);
+        case "task":
+            return runTaskCli(rest, deps);
         case "doctor":
             return { stdout: runDoctor(deps), exitCode: 0 };
         default:
@@ -43,13 +47,15 @@ function runStatus(deps) {
     const kankakuDir = resolveKankakuDir(deps.env.KANKAKU_DIR ?? ".kankaku", deps.cwd);
     const claudeDir = join(kankakuDir, "claude");
     const files = listStateFiles(claudeDir);
+    const resolved = resolveSessionWorkTarget(deps);
+    const targetLine = `${formatTargetLine(resolved)}\n${formatTaskLine(resolved)}`;
     if (files.length === 0) {
-        return { stdout: "No active sessions.\n", exitCode: 0 };
+        return { stdout: `${targetLine}\nNo active sessions.\n`, exitCode: 0 };
     }
     const lines = files
         .sort()
         .map((file) => formatStatusLine(sessionIdFromStateFile(file), file, deps.isAlive, deps.env));
-    return { stdout: lines.join("\n") + "\n", exitCode: 0 };
+    return { stdout: [targetLine, ...lines].join("\n") + "\n", exitCode: 0 };
 }
 function formatStatusLine(sessionId, stateFile, isAlive, env) {
     const state = readState(stateFile);

package/dist/cli.js

@@ -1,7 +1,7 @@
 import { fileURLToPath } from "node:url";
 import { dirname } from "node:path";
 import { runCli } from "./cli-core.js";
-import { isAlive } from "./claude-pid.js";
+import { isAlive, runPsProcess } from "./claude-pid.js";
 // src/cli.ts -> src -> repo root (the directory that contains .claude-plugin/).
 const pluginRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 const result = await runCli(process.argv.slice(2), {
@@ -10,6 +10,8 @@ const result = await runCli(process.argv.slice(2), {
     now: () => Date.now(),
     isAlive,
     pluginRoot,
+    pid: process.pid,
+    runPs: runPsProcess,
 });
 if (result.stdout)
     process.stdout.write(result.stdout);

package/dist/doctor.js

@@ -5,6 +5,7 @@ import { JsonlWorkLog, SyncStateStore, computeSyncStatus, resolveHubCredentials
 import { costDir } from "./cost-store.js";
 import { listStateFiles, resolveKankakuDir } from "./paths.js";
 import { readState } from "./session-state.js";
+import { formatTargetLine, formatTaskLine, resolveSessionWorkTarget } from "./work-target.js";
 function metadata(file) {
     try {
         const value = JSON.parse(readFileSync(file, "utf8"));
@@ -22,6 +23,10 @@ function syncWindowHours(env) {
     const hours = Number(env.KANKAKU_SYNC_WINDOW_HOURS);
     return env.KANKAKU_SYNC_WINDOW_HOURS && Number.isFinite(hours) && hours > 0 ? hours : 24;
 }
+function workTargetLines(deps) {
+    const resolved = resolveSessionWorkTarget(deps);
+    return [formatTargetLine(resolved), formatTaskLine(resolved)];
+}
 /** Read-only, local diagnostic. No sync runner or network client is reachable from this path. */
 export function runDoctor(deps) {
     const dir = resolveKankakuDir(deps.env.KANKAKU_DIR ?? ".kankaku", deps.cwd);
@@ -64,7 +69,7 @@ export function runDoctor(deps) {
     const target = hub.credentials?.url ?? store.read()?.target ?? "";
     const { state, pending, staleOutsideWindow } = computeSyncStatus(log, store, target, syncWindowHours(deps.env));
     const hubState = hub.invalidReason ? "invalid URL" : hub.credentials ? "configured" : "unconfigured";
-    const commands = ["report", "status", "setup", "sync", "sync-status", "sync-all", "doctor"];
+    const commands = ["report", "status", "setup", "sync", "sync-status", "sync-all", "doctor", "task"];
     const present = commands.filter((name) => existsSync(join(deps.pluginRoot, "commands", `${name}.md`))).length;
     const actions = ["/kankaku:status", "/kankaku:sync-status"];
     if (!costsVisible)
@@ -88,6 +93,8 @@ export function runDoctor(deps) {
         `active sessions: ${states.length}`,
         `alive: ${alive}; dead: ${dead}; open prompts: ${open}; unreadable: ${unreadable}`,
         `cost files visible: ${costsVisible ? "yes" : "no"} (current HOME)`,
+        "", "## Work target",
+        ...workTargetLines(deps),
         "", "## Hub / sync",
         `hub: ${hubState}`,
         `pending: ${pending}`,

package/dist/find-session.js

@@ -0,0 +1,43 @@
+import { statSync } from "node:fs";
+import { basename } from "node:path";
+import { resolveClaudePid } from "./claude-pid.js";
+import { readEventLog } from "./event-log.js";
+import { listStateFiles } from "./paths.js";
+import { readState } from "./session-state.js";
+const SESSION_ID = /^[\w.-]+$/;
+function activity(stateFile) {
+    let latest = 0;
+    try {
+        latest = statSync(stateFile).mtimeMs;
+    }
+    catch { /* unreadable: oldest */ }
+    const events = readEventLog(stateFile.replace(/\.state\.json$/, ".events.jsonl"));
+    const last = events[events.length - 1]?.ts;
+    return typeof last === "number" && last > latest ? last : latest;
+}
+/**
+ * The Claude Code session this CLI process runs under: `KANKAKU_CLAUDE_SESSION`
+ * (a plain session id) wins; otherwise the CLI's pid is walked up to the
+ * Claude process and matched against the project's session state files
+ * (`pid`), most recent activity first. `undefined` when nothing matches.
+ */
+export function findSession(input) {
+    const override = input.env.KANKAKU_CLAUDE_SESSION?.trim();
+    if (override && SESSION_ID.test(override))
+        return override;
+    if (input.pid === undefined || input.runPs === undefined)
+        return undefined;
+    const claudePid = resolveClaudePid({ startPid: input.pid, runPs: input.runPs });
+    if (!Number.isSafeInteger(claudePid) || claudePid <= 0)
+        return undefined;
+    const list = input.listStateFiles ?? listStateFiles;
+    let best;
+    for (const file of list(input.claudeDir)) {
+        if (readState(file)?.pid !== claudePid)
+            continue;
+        const at = activity(file);
+        if (!best || at > best.at)
+            best = { id: basename(file).replace(/\.state\.json$/, ""), at };
+    }
+    return best?.id;
+}

package/dist/handle-hook.js

@@ -135,7 +135,8 @@ async function handleStop(paths, sessionId, deps) {
         : undefined;
     const core = replayPrompt(last, { cost: costDelta });
     if (core) {
-        const record = buildClaudeRecord(core, state, sessionId, cost?.model);
+        const assignment = await assignmentResolver(paths, deps);
+        const record = buildClaudeRecord(core, state, sessionId, cost?.model, assignment(state.cwd, sessionId));
         const log = deps.log ?? new JsonlWorkLog(paths.kankakuDir);
         log.append(record);
     }
@@ -155,6 +156,7 @@ async function handleSessionStart(paths, sessionId, cwd, source, ts, deps) {
             isAlive: deps.isAlive,
             now: deps.now(),
             env: deps.env,
+            resolveAssignment: await assignmentResolver(paths, deps),
         });
         if (recovered.length > 0) {
             const log = deps.log ?? new JsonlWorkLog(paths.kankakuDir);
@@ -195,7 +197,8 @@ async function handleSessionEnd(paths, sessionId, cwd, ts, deps) {
             const core = replayPrompt(last, { settledAt: ts });
             if (core) {
                 const model = readCost(deps.env, sessionId)?.model;
-                const record = buildClaudeRecord(core, state, sessionId, 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);
             }
@@ -209,6 +212,46 @@ async function handleSessionEnd(paths, sessionId, cwd, ts, deps) {
         deleteCost(deps.env, sessionId);
     }
 }
+/**
+ * Loads the work-target resolver (a heavy module) and returns a per-cwd
+ * lookup that never throws: any failure means "no assignment", exactly the
+ * unassigned behaviour. Heavy hooks only.
+ */
+async function assignmentResolver(paths, deps) {
+    try {
+        const { resolveClaudeWorkTarget } = await import("./work-target.js");
+        const { homedir } = await import("node:os");
+        const { readSessionTarget } = await import("./session-target-store.js");
+        const { resolveTargetFile } = await import("./paths.js");
+        const resolve = deps.resolveTarget ?? resolveClaudeWorkTarget;
+        return (cwd, sessionId) => {
+            try {
+                // The session-only task link (`/kankaku:task`); heavy hooks only.
+                const stored = readSessionTarget(resolveTargetFile(paths.claudeDir, sessionId));
+                const { target, legacyClient } = resolve({
+                    cwd,
+                    kankakuDir: paths.kankakuDir,
+                    homeDir: deps.env.HOME || homedir(),
+                    env: deps.env,
+                    ...(stored?.hubTaskId !== undefined
+                        ? { taskLink: { hubTaskId: stored.hubTaskId, ...(stored.hubTaskTitle !== undefined ? { hubTaskTitle: stored.hubTaskTitle } : {}) } }
+                        : {}),
+                });
+                return {
+                    ...(target !== undefined ? { target } : {}),
+                    ...(legacyClient !== undefined ? { legacyClient } : {}),
+                };
+            }
+            catch (error) {
+                deps.stderr(`kankaku: work target: ${error instanceof Error ? error.message : String(error)}`);
+                return {};
+            }
+        };
+    }
+    catch {
+        return () => ({});
+    }
+}
 async function syncHeavy(trigger, cwd, deps) {
     try {
         if (deps.autoSync)
@@ -223,7 +266,7 @@ async function syncHeavy(trigger, cwd, deps) {
     }
 }
 function deleteSessionFiles(paths) {
-    for (const file of [paths.stateFile, paths.eventsFile]) {
+    for (const file of [paths.stateFile, paths.eventsFile, paths.targetFile]) {
         try {
             unlinkSync(file);
         }

package/dist/inflight-recovery.js

@@ -1,6 +1,6 @@
 import { unlinkSync } from "node:fs";
 import { basename } from "node:path";
-import { listStateFiles } from "./paths.js";
+import { listStateFiles, resolveTargetFile } from "./paths.js";
 import { readState } from "./session-state.js";
 import { readEventLog } from "./event-log.js";
 import { splitPrompts, replayPrompt } from "./replay.js";
@@ -26,9 +26,11 @@ export function recoverStaleSessions(input) {
             continue;
         const state = readState(stateFile);
         const eventsFile = stateFile.replace(/\.state\.json$/, ".events.jsonl");
+        const targetFile = resolveTargetFile(input.claudeDir, sessionId);
         if (!state) {
             safeUnlink(stateFile);
             safeUnlink(eventsFile);
+            safeUnlink(targetFile);
             continue;
         }
         const dead = state.pid <= 0 || !input.isAlive(state.pid);
@@ -39,15 +41,21 @@ export function recoverStaleSessions(input) {
             const prompts = splitPrompts(events);
             const last = prompts[prompts.length - 1];
             if (last && last.open) {
-                const core = replayPrompt(last, { settledAt: input.now });
+                // 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 core = replayPrompt(last, { settledAt });
                 if (core) {
                     const model = readCost(input.env, sessionId)?.model;
-                    records.push(buildClaudeRecord(core, state, sessionId, model));
+                    records.push(buildClaudeRecord(core, state, sessionId, model, input.resolveAssignment?.(state.cwd, sessionId)));
                 }
             }
         }
         safeUnlink(stateFile);
         safeUnlink(eventsFile);
+        safeUnlink(targetFile);
         deleteCost(input.env, sessionId);
     }
     return records;

package/dist/paths.js

@@ -18,6 +18,7 @@ export function resolvePaths(input) {
         claudeDir,
         eventsFile: join(claudeDir, `${input.sessionId}.events.jsonl`),
         stateFile: join(claudeDir, `${input.sessionId}.state.json`),
+        targetFile: resolveTargetFile(claudeDir, input.sessionId),
     };
 }
 /** Every `*.state.json` path in `claudeDir`, absolute. Empty array when the directory does not exist. */
@@ -33,3 +34,7 @@ export function listStateFiles(claudeDir) {
         .filter((name) => name.endsWith(".state.json"))
         .map((name) => join(claudeDir, name));
 }
+/** `<claudeDir>/<sessionId>.target.json`: the session-only task link (see `session-target-store.ts`). */
+export function resolveTargetFile(claudeDir, sessionId) {
+    return join(claudeDir, `${sessionId}.target.json`);
+}

package/dist/record.js

@@ -1,12 +1,36 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** `version` from a `package.json`, or `undefined` when unreadable — never guessed. */
+export function readPackageVersion(file) {
+    try {
+        const pkg = JSON.parse(readFileSync(file, "utf8"));
+        return typeof pkg.version === "string" && pkg.version !== "" ? pkg.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// 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"));
 /**
  * Attaches the orchestrator metadata a replayed {@link WorkRecordCore}
- * needs to become a persistable {@link WorkRecord}. Phase 1: no
- * `client`/`clientId` (hub sync is phase 2). `model` is the statusline
+ * needs to become a persistable {@link WorkRecord}. `assignment` carries the
+ * resolved hub target (`clientId`, `clientName`, `projectId`, `projectName`)
+ * and the legacy `client` label, stamped exactly as the pi extension does;
+ * omitted, the record is unassigned. `model` is the statusline
  * model id (from `src/cost-store.ts#readCost`, since T7 no longer a field
  * of `SessionState`) — passed in explicitly rather than read here, so the
  * caller decides which cost snapshot's model applies.
+ *
+ * Also stamps who MEASURED the record (`agent`, `plugin`, `pluginVersion`),
+ * so a worklog later synced by another tool (the kankaku TUI) 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.
  */
-export function buildClaudeRecord(core, state, sessionId, model) {
+export function buildClaudeRecord(core, state, sessionId, model, assignment = {}) {
+    const { target, legacyClient } = assignment;
     return {
         ...core,
         role: "orchestrator",
@@ -15,6 +39,20 @@ export function buildClaudeRecord(core, state, sessionId, model) {
         project: state.cwd,
         sessionId,
         mode: "claude-code",
+        agent: "claude-code",
+        plugin: "kankaku-claude",
+        ...(PLUGIN_VERSION !== undefined ? { pluginVersion: PLUGIN_VERSION } : {}),
         ...(model ? { model: `anthropic/${model}` } : {}),
+        ...(legacyClient !== undefined ? { client: legacyClient } : {}),
+        ...(target !== undefined
+            ? {
+                clientId: target.clientId,
+                clientName: target.clientName,
+                ...(target.projectId !== undefined ? { projectId: target.projectId } : {}),
+                ...(target.projectName !== undefined ? { projectName: target.projectName } : {}),
+                ...(target.hubTaskId !== undefined ? { hubTaskId: target.hubTaskId } : {}),
+                ...(target.hubTaskId !== undefined && target.hubTaskTitle !== undefined ? { hubTaskTitle: target.hubTaskTitle } : {}),
+            }
+            : {}),
     };
 }

package/dist/session-target-store.js

@@ -0,0 +1,39 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+function str(value) {
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+/** `undefined` when the file is absent or malformed. Extra or invalid fields are dropped. */
+export function readSessionTarget(file) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return undefined;
+    const o = parsed;
+    if (o.hubTaskId !== undefined && typeof o.hubTaskId !== "string")
+        return undefined;
+    if (o.lastList !== undefined && !Array.isArray(o.lastList))
+        return undefined;
+    const hubTaskId = str(o.hubTaskId);
+    const hubTaskTitle = str(o.hubTaskTitle);
+    const projectId = str(o.projectId);
+    return {
+        ...(hubTaskId !== undefined ? { hubTaskId } : {}),
+        ...(hubTaskId !== undefined && hubTaskTitle !== undefined ? { hubTaskTitle } : {}),
+        ...(hubTaskId !== undefined && projectId !== undefined ? { projectId } : {}),
+        ...(hubTaskId !== undefined && typeof o.pickedAt === "number" ? { pickedAt: o.pickedAt } : {}),
+        lastList: (Array.isArray(o.lastList) ? o.lastList : []).filter((id) => typeof id === "string"),
+    };
+}
+/** Atomic tmp+rename write, creating parent directories as needed. */
+export function writeSessionTarget(file, link) {
+    mkdirSync(dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, JSON.stringify(link));
+    renameSync(tmp, file);
+}

package/dist/task-cli.js

@@ -0,0 +1,114 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CachedCatalog, PocketBaseClient, createPocketBaseCatalogFetcher, resolveHubCredentials } from "kankaku/hub";
+import { findSession } from "./find-session.js";
+import { resolveKankakuDir, resolveTargetFile } from "./paths.js";
+import { readSessionTarget, writeSessionTarget } from "./session-target-store.js";
+import { listOpenTasks, selectTask } from "./task-select.js";
+import { resolveClaudeWorkTarget } from "./work-target.js";
+const DEFAULT_REFRESH_MS = 3000;
+const NO_SESSION = "no active Claude Code session found for this folder\n";
+const HINT = "pick one with: /kankaku:task <number>";
+const say = (lines, exitCode) => ({ stdout: lines.join("\n") + "\n", exitCode });
+/**
+ * `task [list | clear | <number> | <hub id> | <text>]`: links the hub task
+ * this Claude Code session is working on, session-only (see
+ * `session-target-store.ts`). Not a hook: it may use the network, bounded.
+ */
+export async function runTaskCli(args, deps) {
+    const kankakuDir = resolveKankakuDir(deps.env.KANKAKU_DIR ?? ".kankaku", deps.cwd);
+    const claudeDir = join(kankakuDir, "claude");
+    const session = findSession({
+        claudeDir,
+        env: deps.env,
+        ...(deps.pid !== undefined ? { pid: deps.pid } : {}),
+        ...(deps.runPs !== undefined ? { runPs: deps.runPs } : {}),
+    });
+    if (!session)
+        return { stdout: NO_SESSION, exitCode: 1 };
+    const file = resolveTargetFile(claudeDir, session);
+    const stored = readSessionTarget(file) ?? { lastList: [] };
+    const arg = args.join(" ").trim();
+    if (arg === "clear") {
+        if (stored.hubTaskId === undefined)
+            return say(["no task linked"], 0);
+        writeSessionTarget(file, { lastList: stored.lastList });
+        return say(["task link cleared"], 0);
+    }
+    const homeDir = deps.env.HOME || homedir();
+    const note = await refreshCatalog(deps, homeDir);
+    const prefix = note?.text ? [note.text] : [];
+    const resolved = resolveClaudeWorkTarget({ cwd: deps.cwd, kankakuDir, homeDir, env: deps.env });
+    const projectId = resolved.target?.projectId;
+    if (!resolved.target || projectId === undefined) {
+        const reason = resolved.reason ?? "the resolved client has no project";
+        return say([...prefix, `no project resolved for this folder (${reason}); a task belongs to a project`], 1);
+    }
+    const projectName = resolved.target.projectName ?? projectId;
+    const open = listOpenTasks(note?.tasks ?? [], projectId);
+    if (arg === "" || arg === "list") {
+        if (open.length === 0)
+            return say([...prefix, `no open tasks in project ${projectName}`], 0);
+        writeSessionTarget(file, { ...stored, lastList: open.map((task) => task.id) });
+        return say([...prefix, `open tasks in project ${projectName}:`, ...numbered(open, stored.hubTaskId), HINT], 0);
+    }
+    const selection = selectTask(arg, { open, lastList: stored.lastList });
+    if (selection.kind === "unknown")
+        return say([...prefix, selection.message], 1);
+    if (selection.kind === "ambiguous") {
+        writeSessionTarget(file, { ...stored, lastList: selection.candidates.map((task) => task.id) });
+        return say([...prefix, `several open tasks match "${arg}":`, ...numbered(selection.candidates, stored.hubTaskId), HINT], 1);
+    }
+    const task = selection.task;
+    writeSessionTarget(file, {
+        hubTaskId: task.id, hubTaskTitle: task.title, projectId, pickedAt: deps.now(), lastList: stored.lastList,
+    });
+    return say([...prefix, `linked: ${task.title}`], 0);
+}
+function numbered(tasks, linkedId) {
+    return tasks.map((task, index) => {
+        const ref = task.externalRef ? ` (${task.externalRef})` : "";
+        const linked = task.id === linkedId;
+        return `${linked ? "*" : " "} ${index + 1}. ${task.title}${ref}${linked ? " [linked]" : ""}`;
+    });
+}
+/**
+ * Best-effort refresh bounded by `catalogTimeoutMs`; on failure the cached
+ * snapshot is used and its age reported. `undefined` when there is neither
+ * credentials nor a cache (the project lookup then reports why).
+ */
+async function refreshCatalog(deps, homeDir) {
+    const hub = resolveHubCredentials({ env: deps.env, homeDir: () => homeDir });
+    if (!hub.credentials)
+        return undefined;
+    const client = new PocketBaseClient({ ...hub.credentials, ...(deps.fetch ? { fetch: deps.fetch } : {}) });
+    const catalog = new CachedCatalog({
+        filePath: join(homeDir, ".kankaku", "catalog.json"),
+        url: hub.credentials.url,
+        clock: { now: deps.now },
+        fetchCatalog: createPocketBaseCatalogFetcher(client),
+    });
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => { controller.abort(); resolve(undefined); }, deps.catalogTimeoutMs ?? DEFAULT_REFRESH_MS);
+    });
+    const fresh = await Promise.race([catalog.refresh(controller.signal), timeout]);
+    clearTimeout(timer);
+    if (fresh)
+        return { tasks: fresh.tasks ?? [] };
+    const cached = catalog.read();
+    if (!cached)
+        return undefined;
+    return { tasks: cached.tasks ?? [], text: `catalog from cache, ${formatAge(deps.now() - cached.fetchedAt)} old` };
+}
+function formatAge(ms) {
+    const seconds = Math.max(0, Math.round(ms / 1000));
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    return hours < 24 ? `${hours}h` : `${Math.floor(hours / 24)}d`;
+}

package/dist/task-select.js

@@ -0,0 +1,50 @@
+/**
+ * Pure task selection for `/kankaku:task`. Mirrors pi's picker
+ * (`adapters/target-picker.ts#pickHubTask`): a task is pickable when its
+ * status is not `done` (the hub's statuses are `open | doing | done`, see
+ * `HubTask` in `kankaku/domain`) and it belongs to the resolved project.
+ */
+export function isOpenTask(task) {
+    return task.status !== "done";
+}
+/** The project's open tasks, sorted by title (the order the list is numbered in). */
+export function listOpenTasks(tasks, projectId) {
+    return tasks
+        .filter((task) => task.projectId === projectId && isOpenTask(task))
+        .sort((a, b) => a.title.localeCompare(b.title));
+}
+/**
+ * `arg` is one of: a list number (a purely numeric argument is ALWAYS a
+ * number, never an id), a hub id, or a case-insensitive title substring
+ * that must match exactly one open task.
+ */
+export function selectTask(arg, ctx) {
+    const text = arg.trim();
+    if (text === "")
+        return { kind: "unknown", message: "no task given" };
+    if (/^-?\d+$/.test(text))
+        return selectByNumber(Number(text), ctx);
+    const byId = ctx.open.find((task) => task.id === text);
+    if (byId)
+        return { kind: "picked", task: byId };
+    const needle = text.toLowerCase();
+    const matches = ctx.open.filter((task) => task.title.toLowerCase().includes(needle));
+    if (matches.length === 1)
+        return { kind: "picked", task: matches[0] };
+    if (matches.length > 1)
+        return { kind: "ambiguous", candidates: matches };
+    return { kind: "unknown", message: `no open task matches "${text}"` };
+}
+function selectByNumber(n, ctx) {
+    if (ctx.lastList.length === 0) {
+        return { kind: "unknown", message: "no task list shown yet in this session; list the tasks first" };
+    }
+    if (!Number.isSafeInteger(n) || n < 1 || n > ctx.lastList.length) {
+        return { kind: "unknown", message: `${n} is not on the list (1-${ctx.lastList.length})` };
+    }
+    const id = ctx.lastList[n - 1];
+    const task = ctx.open.find((candidate) => candidate.id === id);
+    if (!task)
+        return { kind: "unknown", message: `task ${n} is no longer open; list the tasks again` };
+    return { kind: "picked", task };
+}

package/dist/work-target.js

@@ -0,0 +1,123 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CachedCatalog, readProjectClient, readProjectTargetIds, resolveHubCredentials, } from "kankaku/hub";
+import { formatWorkTargetLabel, isValidClient, resolveClient, resolveWorkTarget, resolveWorkTargetSource, } from "kankaku/domain";
+import { findSession } from "./find-session.js";
+import { resolveKankakuDir, resolveTargetFile } from "./paths.js";
+import { readSessionTarget } from "./session-target-store.js";
+/**
+ * Resolves the work target for a session, for record stamping and display.
+ *
+ * Sources, in order: the project's `config.json` ids, then the cached
+ * catalog's `repo_paths` match for `cwd`. The catalog comes only from the
+ * cache file that every real sync refreshes — there is no fetch, no refresh
+ * and no network here, and nothing throws: an unusable cache means "no
+ * target". The precedence and eligibility rules (active, not the
+ * "unassigned" client, project belongs to the client) live entirely in the
+ * library's `resolveWorkTarget`.
+ *
+ * Only the heavy hooks (Stop, SessionEnd, recovery) and the CLI call this;
+ * the per-tool-call hooks never do.
+ */
+export function resolveClaudeWorkTarget(input) {
+    try {
+        return resolveUnsafe(input);
+    }
+    catch {
+        return { reason: "no catalog cache" };
+    }
+}
+function resolveUnsafe(input) {
+    const projectClient = readProjectClient(input.kankakuDir);
+    const legacyFallback = resolveClient({ env: input.env.KANKAKU_CLIENT, project: projectClient });
+    const link = input.taskLink;
+    const dropped = link !== undefined ? { droppedTask: { title: link.hubTaskTitle ?? link.hubTaskId } } : {};
+    const withLegacy = (result) => {
+        const base = result.target === undefined ? { ...result, ...dropped } : result;
+        return legacyFallback !== undefined ? { ...base, legacyClient: legacyFallback } : base;
+    };
+    const snapshot = readCatalogCache(input);
+    if (!snapshot)
+        return withLegacy({ reason: "no catalog cache" });
+    const resolveInput = {
+        project: readProjectTargetIds(input.kankakuDir),
+        cwd: input.cwd,
+        clients: snapshot.clients,
+        projects: snapshot.projects,
+    };
+    const target = resolveWorkTarget(resolveInput);
+    const source = resolveWorkTargetSource(resolveInput);
+    if (!target || (source !== "project" && source !== "repoPaths")) {
+        return withLegacy({ reason: `no match for ${input.cwd}` });
+    }
+    // Mirrors the pi extension: with a hub target the legacy label is the
+    // client's code, omitted when it is not a valid label.
+    // A linked task is validated by the library as the session source's task:
+    // same client and project as resolved above, so it can only ever add the
+    // task (kept when it belongs to that project and is still in the catalog).
+    const withTask = link !== undefined && target.projectId !== undefined
+        ? resolveWorkTarget({
+            ...resolveInput,
+            session: { clientId: target.clientId, projectId: target.projectId, hubTaskId: link.hubTaskId },
+            tasks: snapshot.tasks ?? [],
+        })
+        : undefined;
+    const finalTarget = withTask?.hubTaskId !== undefined ? withTask : target;
+    return {
+        target: finalTarget,
+        source,
+        ...(link !== undefined && finalTarget.hubTaskId === undefined ? dropped : {}),
+        ...(isValidClient(target.clientCode) ? { legacyClient: target.clientCode } : {}),
+    };
+}
+function readCatalogCache(input) {
+    // The cache is keyed by hub url; the url comes from credentials (env or
+    // file), which are read locally. No credentials, no way to trust a cache.
+    const hub = resolveHubCredentials({ env: input.env, homeDir: () => input.homeDir });
+    if (!hub.credentials)
+        return undefined;
+    return new CachedCatalog({
+        filePath: join(input.homeDir, ".kankaku", "catalog.json"),
+        url: hub.credentials.url,
+        clock: { now: () => 0 }, // read() never consults the clock
+        fetchCatalog: () => Promise.reject(new Error("the hook path never fetches")),
+    }).read();
+}
+/** The `target:` line printed by `/kankaku:status` and `/kankaku:doctor`. */
+export function formatTargetLine(result) {
+    if (!result.target)
+        return `target: none (${result.reason ?? "unresolved"})`;
+    const source = result.source === "project" ? "project config" : "repo_paths";
+    // The task has its own line (see formatTaskLine); keep this one to client and project.
+    const { hubTaskId: _id, hubTaskTitle: _title, ...bare } = result.target;
+    return `target: ${formatWorkTargetLabel(bare)} (source: ${source})`;
+}
+/** The `task:` line printed by `/kankaku:status` and `/kankaku:doctor`. */
+export function formatTaskLine(result) {
+    if (result.target?.hubTaskTitle !== undefined)
+        return `task: ${result.target.hubTaskTitle}`;
+    if (result.droppedTask === undefined)
+        return "task: none";
+    const where = result.target?.projectName !== undefined ? `is not in project ${result.target.projectName}` : "needs a project";
+    return `task: none (linked task "${result.droppedTask.title}" ${where})`;
+}
+/**
+ * The work target for display (`status`, `doctor`): the folder's target plus
+ * the task linked by the session this process runs under, when one is found.
+ */
+export function resolveSessionWorkTarget(deps) {
+    const kankakuDir = resolveKankakuDir(deps.env.KANKAKU_DIR ?? ".kankaku", deps.cwd);
+    const claudeDir = join(kankakuDir, "claude");
+    const session = findSession({
+        claudeDir, env: deps.env,
+        ...(deps.pid !== undefined ? { pid: deps.pid } : {}),
+        ...(deps.runPs !== undefined ? { runPs: deps.runPs } : {}),
+    });
+    const stored = session !== undefined ? readSessionTarget(resolveTargetFile(claudeDir, session)) : undefined;
+    return resolveClaudeWorkTarget({
+        cwd: deps.cwd, kankakuDir, homeDir: deps.env.HOME || homedir(), env: deps.env,
+        ...(stored?.hubTaskId !== undefined
+            ? { taskLink: { hubTaskId: stored.hubTaskId, ...(stored.hubTaskTitle !== undefined ? { hubTaskTitle: stored.hubTaskTitle } : {}) } }
+            : {}),
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kankaku-claude",
-  "version": "0.10.0",
+  "version": "0.12.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": "^0.10.0"
+    "kankaku": "^0.12.0"
   },
   "devDependencies": {
     "@types/node": "^24.13.4",