feat(v0.10.0)!: PostToolUse asyncRewake — zero-latency happy path, wake on backlog

Adopt the undocumented Claude Code 2.1.x asyncRewake hook field
(verified in 2.1.160's Zod schema: asyncRewake + rewakeMessage +
rewakeSummary). PostToolUse hook now runs entirely in background;
model never blocks on `task-journal ingest-hook` on success path.

When pending/ grows past PENDING_OVERFLOW_THRESHOLD (25), the hook
exits 2 — Claude Code interprets as "wake model with system reminder".
User sees rewakeSummary "Task Journal backlog forming" plus hook
stdout pointing at `task-journal pending-gc --days 0`. Classifier-
behind state surfaces before queue grows to hundreds.

Wake-signal gated on TJ_ASYNC_REWAKE=1 env var, set ONLY by the
PostToolUse hook command in hooks.json. CLI invocations + sync
PreCompact/Stop hooks never exit 2 even on overflow — exit 2 from
a sync hook would BLOCK the operation in Claude Code's contract.

Closes tj-857 (X1) under tj-h7d (v0.10.x epic). Plan tj-813 (X2),
tj-x3t (X3), tj-aym (X4) tracked separately.

Migration: `task-journal install-hooks --uninstall && task-journal
install-hooks` to pick up new hook contract. Claude Code 2.1.x+
required for asyncRewake recognition (older versions silently fall
back to synchronous behavior).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: Shahinyanm

CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-06-02
+
+**`asyncRewake` on PostToolUse — zero-latency happy path, wake on backlog.**
+Adopts the undocumented `asyncRewake: true` Claude Code hook field (verified
+present in 2.1.160's Zod schema as `asyncRewake` + `rewakeMessage` +
+`rewakeSummary`). The PostToolUse hook now runs entirely in the background:
+the model never blocks on `task-journal ingest-hook` on the success path,
+even though the binary still does its full persist-to-`pending/` + spawn-
+classify-worker work. When the pending queue grows past 25 entries, the
+hook exits with code 2, which Claude Code interprets as "wake the model
+with a system reminder." The model sees `rewakeSummary` ("Task Journal
+backlog forming") plus the hook's stdout — a one-liner pointing at
+`task-journal pending-gc --days 0`. The classifier-can't-keep-up state
+becomes visible BEFORE it grows into the hundreds (the v0.6.2 fork-bomb
+era saw 515 entries before a user noticed).
+
+PreCompact and Stop hooks stay synchronous — they do transcript catch-up
+that must finish before compaction/exit, and exit code 2 from a sync
+hook BLOCKS the operation in Claude Code's contract. The wake-signal is
+gated on `TJ_ASYNC_REWAKE=1`, which only the PostToolUse hook command
+sets; CLI invocations and sync hooks never exit 2 even on overflow.
+
+### Added
+- `PENDING_OVERFLOW_THRESHOLD = 25` const and `count_pending_entries`
+  helper in `tj-cli` — best-effort directory count, IO errors return 0
+  so a borked filesystem never wakes the model with noise.
+- 3 new integration tests: `asyncrewake_below_threshold_exits_zero`,
+  `asyncrewake_overflow_exits_two_with_drain_hint`,
+  `asyncrewake_overflow_without_env_does_not_exit_two` — the last one
+  is the sync-hook safety guarantee.
+
+### Changed
+- `plugin/hooks/hooks.json` PostToolUse entry now declares
+  `"asyncRewake": true` + `"rewakeSummary": "Task Journal backlog forming"`
+  and the command sets `TJ_ASYNC_REWAKE=1`. Dropped the trailing
+  `|| true` from the PostToolUse command — asyncRewake hooks treat
+  exit codes themselves; other exit codes are ignored, only code 2
+  wakes. PreCompact and Stop entries are unchanged.
+
+### Migration
+- `task-journal install-hooks --uninstall && task-journal install-hooks`
+  to pick up the new hook contract. Claude Code 2.1.x or later required
+  for the `asyncRewake` field to be recognized (silently ignored on
+  older versions — they will run the PostToolUse hook synchronously
+  as a fallback). The 25-entry threshold is hard-coded for v0.10.0;
+  later releases may make it configurable.
+
 ## [0.9.4] - 2026-05-17
 
 ### Fixed

Cargo.lock

@@ -7,7 +7,7 @@ members = [
 ]
 
 [workspace.package]
-version = "0.9.4"
+version = "0.10.0"
 edition = "2021"
 rust-version = "1.88"
 license = "MIT"

Cargo.toml

@@ -16,7 +16,7 @@ name = "task-journal"
 path = "src/main.rs"
 
 [dependencies]
-tj-core = { package = "task-journal-core", version = "0.9.4", path = "../tj-core" }
+tj-core = { package = "task-journal-core", version = "0.10.0", path = "../tj-core" }
 anyhow = { workspace = true }
 clap = { workspace = true }
 tracing = { workspace = true }

crates/tj-cli/Cargo.toml

@@ -1775,6 +1775,25 @@ fn main() -> Result<()> {
                 // a failure to spawn just means the entry sits in
                 // pending/ until the next hook fires another spawn.
                 let _ = spawn_classify_worker(&backend);
+
+                // v0.10.0 asyncRewake backlog signal. Only the PostToolUse
+                // hook runs as asyncRewake (hooks.json sets TJ_ASYNC_REWAKE=1
+                // there), so other kinds — and direct CLI invocations —
+                // never exit 2 even on overflow. Exit code 2 from a sync
+                // hook would BLOCK the operation; only asyncRewake hooks
+                // treat code 2 as "wake the model with rewakeMessage". stdout
+                // is appended to the wake message, so the user sees the
+                // drain command without us reaching into stderr.
+                let allow_wake = std::env::var("TJ_ASYNC_REWAKE").as_deref() == Ok("1");
+                if allow_wake && kind == "PostToolUse" {
+                    let pending_count = count_pending_entries(&events_path).unwrap_or(0);
+                    if pending_count > PENDING_OVERFLOW_THRESHOLD {
+                        println!(
+                            "Task Journal pending queue: {pending_count} entries. Classifier behind — run `task-journal pending-gc --days 0` to drain.",
+                        );
+                        std::process::exit(2);
+                    }
+                }
                 return Ok(());
             }
 
@@ -2844,6 +2863,41 @@ fn persist_pending(events_path: &std::path::Path, text: &str, err: &str) -> anyh
 /// v0.6.2: queue an ingest event for the detached classify-worker. The
 /// hook returns immediately after writing this entry so it does not
 /// block Claude Code's hook timeout (was 5-30s, now <100ms). Schema "v2"
+/// Threshold for the v0.10.0 asyncRewake backlog signal. When the
+/// PostToolUse hook (configured with `asyncRewake: true` in
+/// `hooks.json`) finds more than this many entries already queued
+/// in `pending/`, it exits with code 2 to wake the model with a
+/// system reminder pointing at `task-journal pending-gc`. Tuned so
+/// that normal load (<5 in-flight at any moment) never trips, but
+/// a stuck classifier surfaces visibly before the queue grows into
+/// the hundreds (the v0.6.2 fork-bomb era saw 515 entries before a
+/// user noticed).
+const PENDING_OVERFLOW_THRESHOLD: usize = 25;
+
+/// Count `.json` (and `.json.dead`) entries currently sitting in
+/// `pending/` next to `events_path`. Best-effort: any IO error
+/// returns 0 so a borked filesystem never wakes the model with
+/// noise. Used by the asyncRewake backlog signal.
+fn count_pending_entries(events_path: &std::path::Path) -> anyhow::Result<usize> {
+    let dir = events_path
+        .parent()
+        .and_then(|p| p.parent())
+        .ok_or_else(|| anyhow::anyhow!("events_path has no grandparent"))?
+        .join("pending");
+    if !dir.exists() {
+        return Ok(0);
+    }
+    let mut count = 0usize;
+    for entry in std::fs::read_dir(&dir)? {
+        let entry = entry?;
+        let path = entry.path();
+        if let Some("json") = path.extension().and_then(|e| e.to_str()) {
+            count += 1;
+        }
+    }
+    Ok(count)
+}
+
 /// distinguishes async-ingest entries from legacy v1 (text+error) ones
 /// the `pending retry` path knows how to handle.
 fn persist_pending_v2(

crates/tj-cli/src/main.rs

@@ -2966,3 +2966,135 @@ fn export_pr_unknown_task_id_exits_one_with_stderr_message() {
         .failure()
         .stderr(contains("task not found: tj-zzzz"));
 }
+
+// v0.10.0: asyncRewake backlog signal. PostToolUse hook configured with
+// asyncRewake:true in hooks.json sets TJ_ASYNC_REWAKE=1; when pending/
+// has more than PENDING_OVERFLOW_THRESHOLD (25) entries already queued,
+// ingest-hook exits 2 with a wake-message on stdout. Sync hooks (or
+// CLI invocations without the env var) must NEVER exit 2 — that would
+// block the operation in Claude Code's hook contract.
+fn seed_pending_chunks(pending_dir: &std::path::Path, count: usize) {
+    std::fs::create_dir_all(pending_dir).unwrap();
+    for i in 0..count {
+        let payload = serde_json::json!({
+            "schema": "v2",
+            "kind": "PostToolUse",
+            "text": format!("seed-{i}"),
+            "project_hash": "deadbeefdeadbeef",
+            "events_path": "/tmp/unused.jsonl",
+            "backend": "hybrid",
+            "queued_at": "2099-01-01T00:00:00Z",
+        });
+        std::fs::write(
+            pending_dir.join(format!("seed-{i:04}.json")),
+            serde_json::to_string_pretty(&payload).unwrap(),
+        )
+        .unwrap();
+    }
+}
+
+fn posttooluse_payload() -> String {
+    serde_json::json!({
+        "hook_event_name": "PostToolUse",
+        "tool_name": "Bash",
+        "tool_input": {"command": "echo hi"},
+        "tool_response": {"stdout": "hi"},
+    })
+    .to_string()
+}
+
+#[test]
+fn asyncrewake_below_threshold_exits_zero() {
+    let dir = assert_fs::TempDir::new().unwrap();
+    let workdir = dir.path().join("proj");
+    std::fs::create_dir_all(&workdir).unwrap();
+
+    Command::cargo_bin("task-journal")
+        .unwrap()
+        .env("XDG_DATA_HOME", dir.path())
+        .current_dir(&workdir)
+        .args(["create", "Async wake test below threshold"])
+        .assert()
+        .success();
+
+    // Seed 5 entries — well under the 25 threshold.
+    let pending = dir.path().join("task-journal").join("pending");
+    seed_pending_chunks(&pending, 5);
+
+    Command::cargo_bin("task-journal")
+        .unwrap()
+        .env("XDG_DATA_HOME", dir.path())
+        .env("TJ_ASYNC_REWAKE", "1")
+        .env("TJ_DISABLE_CLASSIFY_SPAWN", "1")
+        .current_dir(&workdir)
+        .args(["ingest-hook", "--backend", "hybrid"])
+        .write_stdin(posttooluse_payload())
+        .assert()
+        .success(); // exit 0, no wake
+}
+
+#[test]
+fn asyncrewake_overflow_exits_two_with_drain_hint() {
+    let dir = assert_fs::TempDir::new().unwrap();
+    let workdir = dir.path().join("proj");
+    std::fs::create_dir_all(&workdir).unwrap();
+
+    Command::cargo_bin("task-journal")
+        .unwrap()
+        .env("XDG_DATA_HOME", dir.path())
+        .current_dir(&workdir)
+        .args(["create", "Async wake overflow test"])
+        .assert()
+        .success();
+
+    // Seed 30 entries — over the 25 threshold.
+    let pending = dir.path().join("task-journal").join("pending");
+    seed_pending_chunks(&pending, 30);
+
+    Command::cargo_bin("task-journal")
+        .unwrap()
+        .env("XDG_DATA_HOME", dir.path())
+        .env("TJ_ASYNC_REWAKE", "1")
+        .env("TJ_DISABLE_CLASSIFY_SPAWN", "1")
+        .current_dir(&workdir)
+        .args(["ingest-hook", "--backend", "hybrid"])
+        .write_stdin(posttooluse_payload())
+        .assert()
+        .failure()
+        .code(2)
+        .stdout(contains("Task Journal pending queue"))
+        .stdout(contains("pending-gc"));
+}
+
+#[test]
+fn asyncrewake_overflow_without_env_does_not_exit_two() {
+    // Sync hook safety: without TJ_ASYNC_REWAKE=1 we must NEVER exit 2
+    // even on overflow, because exit 2 from a sync hook blocks the
+    // operation in Claude Code. CLI invocations and the PreCompact/Stop
+    // hooks (which stay sync) rely on this guarantee.
+    let dir = assert_fs::TempDir::new().unwrap();
+    let workdir = dir.path().join("proj");
+    std::fs::create_dir_all(&workdir).unwrap();
+
+    Command::cargo_bin("task-journal")
+        .unwrap()
+        .env("XDG_DATA_HOME", dir.path())
+        .current_dir(&workdir)
+        .args(["create", "Sync hook safety test"])
+        .assert()
+        .success();
+
+    let pending = dir.path().join("task-journal").join("pending");
+    seed_pending_chunks(&pending, 30);
+
+    Command::cargo_bin("task-journal")
+        .unwrap()
+        .env("XDG_DATA_HOME", dir.path())
+        .env_remove("TJ_ASYNC_REWAKE")
+        .env("TJ_DISABLE_CLASSIFY_SPAWN", "1")
+        .current_dir(&workdir)
+        .args(["ingest-hook", "--backend", "hybrid"])
+        .write_stdin(posttooluse_payload())
+        .assert()
+        .success(); // exit 0, no wake — must not block sync hooks
+}

crates/tj-cli/tests/cli.rs

@@ -16,7 +16,7 @@ name = "task-journal-mcp"
 path = "src/main.rs"
 
 [dependencies]
-tj-core = { package = "task-journal-core", version = "0.9.4", path = "../tj-core" }
+tj-core = { package = "task-journal-core", version = "0.10.0", path = "../tj-core" }
 anyhow = { workspace = true }
 tokio = { workspace = true }
 tracing = { workspace = true }

crates/tj-mcp/Cargo.toml

@@ -1,6 +1,6 @@
 {
   "name": "task-journal",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "description": "Append-only journal of AI-coding task reasoning chains: hypotheses, decisions, rejections, evidence. Renders compact resume packs so an agent can pick up a 2-week-old task with full context.",
   "author": {
     "name": "Mher Shahinyan"

plugin/.claude-plugin/plugin.json

@@ -6,7 +6,9 @@
         "hooks": [
           {
             "type": "command",
-            "command": "task-journal ingest-hook 2>/dev/null || true"
+            "command": "TJ_ASYNC_REWAKE=1 task-journal ingest-hook 2>/dev/null",
+            "asyncRewake": true,
+            "rewakeSummary": "Task Journal backlog forming"
           }
         ]
       }

plugin/hooks/hooks.json

@@ -1,6 +1,6 @@
 {
   "name": "task-journal",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "description": "Append-only journal of AI-coding task reasoning chains. Captures hypotheses, decisions, rejections, evidence — renders compact resume packs so an agent can pick up a 2-week-old task with full context.",
   "author": {
     "name": "Mher Shahinyan",