cc-session-recover 0.1.3 → 0.1.5

package/.claude/hooks/remind-on-prompt.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+
+# UserPromptSubmit hook.
+# Injects an unconditional recovery order next to every prompt. Earlier
+# softer wording ("if this is a multi-step task...") left the model
+# discretion, and in long sessions it deferred forever. No judgment calls.
+# Keep this output short: it is added to context on every single prompt.
+
+set -u
+
+printf 'Recovery check (do this before the request itself): if no recurring auto-continue schedule exists in this session, create one now — every 45 minutes, prompt: "Read .claude/auto-continue.md and follow it". Never create a duplicate. On multi-step tasks, update HANDOFF.md after each work step.\n'
+
+exit 0

package/.claude/settings.example.json

@@ -11,6 +11,16 @@
         ]
       }
     ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/remind-on-prompt.sh"
+          }
+        ]
+      }
+    ],
     "StopFailure": [
       {
         "matcher": "rate_limit",

package/.claude/standing-instructions.md

@@ -1,10 +1,12 @@
 Standing quota-recovery instructions for this project:
 
-If the user gives a multi-step coding task in this session:
+At the start of any task in this session — coding, analysis, research, document work, audits, or skill-driven and automated runs:
 
-1. Keep `HANDOFF.md` updated after every small safe step.
-2. Create a recurring schedule every 45 minutes with this prompt: "Read .claude/auto-continue.md and follow it."
-3. Cancel that schedule when the task is fully complete.
+1. Before doing the task itself, check whether this session already has a recurring auto-continue schedule.
+2. If none exists, create one now with Claude Code's scheduler (`CronCreate` or `/loop`). Do this even for short-looking requests; an unused schedule is harmless and you can cancel it when done.
+3. Use this scheduled prompt exactly: "Read .claude/auto-continue.md and follow it."
+4. Prefer a 45-minute recurring interval. If the scheduler cannot represent that cleanly, use a 30-minute recurring interval.
+5. Keep `HANDOFF.md` updated after every small safe step on multi-step tasks.
+6. Cancel the auto-continue schedule when the task is fully complete.
 
-Do not create the schedule for quick questions or single-step requests.
-Do not create a second schedule if one already exists.
+Never create a second schedule if one already exists in this session.

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.1.5 — 2026-06-13
+
+- Add a `UserPromptSubmit` recovery reminder hook so the schedule instruction is repeated next to every prompt, not just at session start (it was getting buried in long sessions).
+- Make the schedule rule unconditional and consistent across both injection points: always ensure one recurring auto-continue schedule exists, instead of leaving the model a "is this a long task?" judgment call that silently skipped audits and skill-driven runs. An explicit user instruction not to schedule still wins.
+- Preserve existing `.claude/settings.local.json` on install by merging the recovery hooks in, rather than skipping when the file exists.
+- Use the quoted `"$CLAUDE_PROJECT_DIR"` form in example hook commands (safe for paths with spaces).
+
+## 0.1.4 — 2026-06-12
+
+- Expand standing quota-recovery instructions to cover long analysis, research, document, and automated workflow tasks, not only coding tasks.
+
 ## 0.1.3 — 2026-06-12
 
 - Install only the runtime `.claude` files and `HANDOFF.md` into target projects; package tooling now stays in the npm package.

package/README.md

@@ -42,6 +42,6 @@ If quota dies mid-task, work resumes automatically after the reset.
 
 ## Docs
 
-- [Simple flow](docs/simple-flow.md) — how it works, told as a story (notebook, alarm, watchman).
-- [FAQ](docs/faq.md) — reliability, hook approval, what still needs a human.
-- [Full details](docs/claude-code-auto-resume.md) — closed-terminal watcher, precise reset-time resume, all limits.
+- [Simple flow](https://github.com/softcane/cc-session-recover/blob/main/docs/simple-flow.md) — how it works, told as a story (notebook, alarm, watchman).
+- [FAQ](https://github.com/softcane/cc-session-recover/blob/main/docs/faq.md) — reliability, hook approval, what still needs a human.
+- [Full details](https://github.com/softcane/cc-session-recover/blob/main/docs/claude-code-auto-resume.md) — closed-terminal watcher, precise reset-time resume, all limits.

package/bin/cli.js

@@ -23,6 +23,7 @@ const FILES = [
   '.claude/statusline-quota-cache.sh',
   '.claude/hooks/log-stop-failure.sh',
   '.claude/hooks/inject-standing-instructions.sh',
+  '.claude/hooks/remind-on-prompt.sh',
 ];
 
 const COPY_IF_MISSING = ['HANDOFF.md'];
@@ -38,6 +39,66 @@ const IGNORE_ENTRIES = [
   '.claude/quota-blocked.json',
 ];
 const IGNORE_HEADER = '# Claude Code session-recovery runtime state';
+const RECOVERY_HOOK_SCRIPTS = [
+  'inject-standing-instructions.sh',
+  'remind-on-prompt.sh',
+  'log-stop-failure.sh',
+];
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    throw new Error(`Could not parse ${file}: ${err.message}`);
+  }
+}
+
+function addMissingHookGroups(existingGroups, incomingGroups) {
+  const merged = Array.isArray(existingGroups) ? existingGroups.slice() : [];
+  for (const group of incomingGroups || []) {
+    const encoded = JSON.stringify(group);
+    if (!merged.some((existing) => JSON.stringify(existing) === encoded || hasSameRecoveryHook(existing, group))) {
+      merged.push(group);
+    }
+  }
+  return merged;
+}
+
+function recoveryHookScripts(group) {
+  const handlers = Array.isArray(group && group.hooks) ? group.hooks : [];
+  const commands = handlers
+    .filter((handler) => handler && handler.type === 'command' && typeof handler.command === 'string')
+    .map((handler) => handler.command);
+  return RECOVERY_HOOK_SCRIPTS.filter((script) => commands.some((command) => command.includes(script)));
+}
+
+function hasSameRecoveryHook(existingGroup, incomingGroup) {
+  const incomingScripts = recoveryHookScripts(incomingGroup);
+  if (!incomingScripts.length) return false;
+
+  const existingScripts = recoveryHookScripts(existingGroup);
+  return incomingScripts.some((script) => existingScripts.includes(script));
+}
+
+function mergeHookSettings(localPath, templatePath) {
+  if (!fs.existsSync(localPath)) {
+    fs.copyFileSync(templatePath, localPath);
+    return 'created';
+  }
+
+  const localSettings = readJson(localPath);
+  const templateSettings = readJson(templatePath);
+  const incomingHooks = templateSettings.hooks || {};
+  const mergedHooks = { ...(localSettings.hooks || {}) };
+
+  for (const [event, groups] of Object.entries(incomingHooks)) {
+    mergedHooks[event] = addMissingHookGroups(mergedHooks[event], groups);
+  }
+
+  localSettings.hooks = mergedHooks;
+  fs.writeFileSync(localPath, `${JSON.stringify(localSettings, null, 2)}\n`);
+  return 'merged';
+}
 
 function usage() {
   console.error('Usage: cc-session-recover init [--no-hooks] [target-dir]');
@@ -109,11 +170,9 @@ function main() {
 
   if (enableHook) {
     const local = path.join(target, '.claude', 'settings.local.json');
-    if (fs.existsSync(local)) {
-      console.error('Skipped hook enablement: .claude/settings.local.json already exists.');
-      console.error('Merge .claude/settings.example.json into it manually if wanted.');
-    } else {
-      fs.copyFileSync(path.join(TEMPLATE_ROOT, '.claude', 'settings.example.json'), local);
+    const result = mergeHookSettings(local, path.join(TEMPLATE_ROOT, '.claude', 'settings.example.json'));
+    if (result === 'merged') {
+      console.error('Merged hook settings into existing .claude/settings.local.json.');
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-session-recover",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Quota-resume workflow for Claude Code: handoff notebook, heartbeat auto-continue, StopFailure hooks, and an unattended watcher that resumes after quota resets.",
   "scripts": {
     "check": "node --check bin/cli.js && bash -n scripts/*.sh .claude/hooks/*.sh .claude/statusline-quota-cache.sh && bash scripts/verify-claude-loop-workflow.sh",

package/scripts/install-into-project.sh

@@ -27,12 +27,75 @@ TEMPLATE_ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
   exit 1
 }
 
+merge_hook_settings() {
+  local local_settings=$1
+  local template_settings=$2
+  local tmp
+
+  if [ ! -f "$local_settings" ]; then
+    cp "$template_settings" "$local_settings"
+    return
+  fi
+
+  if ! command -v jq >/dev/null 2>&1; then
+    printf 'Cannot merge hooks into existing .claude/settings.local.json because jq is not on PATH.\n' >&2
+    printf 'Install jq, then rerun this installer.\n' >&2
+    exit 1
+  fi
+
+  tmp=$(mktemp "${local_settings}.tmp.XXXXXX")
+  if jq -s '
+    def recovery_scripts: [
+      "inject-standing-instructions.sh",
+      "remind-on-prompt.sh",
+      "log-stop-failure.sh"
+    ];
+    def as_array: if type == "array" then . else [] end;
+    def as_object: if type == "object" then . else {} end;
+    def recovery_hook_scripts:
+      [(.hooks // [])[]? |
+        select(.type == "command" and (.command | type == "string")) |
+        .command as $command |
+        recovery_scripts[] |
+        select($command | contains(.))
+      ];
+    def same_recovery_hook($existing; $incoming):
+      (recovery_hook_scripts as $existing_scripts |
+        ($incoming | recovery_hook_scripts) as $incoming_scripts |
+        (($incoming_scripts | length) > 0) and
+        any($incoming_scripts[]; . as $script | any($existing_scripts[]; . == $script))
+      );
+    def add_missing($incoming):
+      as_array as $existing |
+      reduce (($incoming // []) | as_array)[] as $item ($existing;
+        if any(.[]; (. == $item) or same_recovery_hook(.; $item)) then . else . + [$item] end
+      );
+    def merge_hooks($incoming):
+      as_object as $base |
+      reduce (($incoming // {}) | as_object | keys_unsorted[]) as $event ($base;
+        .[$event] = (.[$event] | add_missing($incoming[$event]))
+      );
+
+    .[0] as $local |
+    .[1] as $template |
+    $local + {hooks: (($local.hooks // {}) | merge_hooks($template.hooks // {}))}
+  ' "$local_settings" "$template_settings" > "$tmp"; then
+    mv "$tmp" "$local_settings"
+    printf 'Merged hook settings into existing .claude/settings.local.json.\n' >&2
+  else
+    rm -f "$tmp"
+    printf 'Could not merge hooks into .claude/settings.local.json.\n' >&2
+    exit 1
+  fi
+}
+
 mkdir -p "$TARGET/.claude/hooks"
 
 cp "$TEMPLATE_ROOT/.claude/auto-continue.md" "$TARGET/.claude/auto-continue.md"
 cp "$TEMPLATE_ROOT/.claude/standing-instructions.md" "$TARGET/.claude/standing-instructions.md"
 cp "$TEMPLATE_ROOT/.claude/statusline-quota-cache.sh" "$TARGET/.claude/statusline-quota-cache.sh"
 cp "$TEMPLATE_ROOT/.claude/hooks/inject-standing-instructions.sh" "$TARGET/.claude/hooks/inject-standing-instructions.sh"
+cp "$TEMPLATE_ROOT/.claude/hooks/remind-on-prompt.sh" "$TARGET/.claude/hooks/remind-on-prompt.sh"
 cp "$TEMPLATE_ROOT/.claude/settings.example.json" "$TARGET/.claude/settings.example.json"
 cp "$TEMPLATE_ROOT/.claude/hooks/log-stop-failure.sh" "$TARGET/.claude/hooks/log-stop-failure.sh"
 if [ ! -f "$TARGET/HANDOFF.md" ]; then
@@ -41,6 +104,7 @@ fi
 
 chmod +x "$TARGET/.claude/hooks/log-stop-failure.sh"
 chmod +x "$TARGET/.claude/hooks/inject-standing-instructions.sh"
+chmod +x "$TARGET/.claude/hooks/remind-on-prompt.sh"
 chmod +x "$TARGET/.claude/statusline-quota-cache.sh"
 
 # Keep runtime state out of the target's git history. HANDOFF.md must stay in
@@ -72,12 +136,7 @@ for entry in HANDOFF.md .claude/settings.local.json .claude/rate-limit-state.jso
 done
 
 if [ "$ENABLE_LOCAL_HOOK" -eq 1 ]; then
-  if [ -f "$TARGET/.claude/settings.local.json" ]; then
-    printf 'Skipped hook enablement because .claude/settings.local.json already exists.\n' >&2
-    printf 'Merge .claude/settings.example.json into it manually if wanted.\n' >&2
-  else
-    cp "$TEMPLATE_ROOT/.claude/settings.example.json" "$TARGET/.claude/settings.local.json"
-  fi
+  merge_hook_settings "$TARGET/.claude/settings.local.json" "$TEMPLATE_ROOT/.claude/settings.example.json"
 fi
 
 printf 'Installed Claude Code workflow into %s\n' "$TARGET"

package/scripts/test-fake-quota-flow.sh

@@ -44,6 +44,67 @@ bash "$TEMPLATE_ROOT/scripts/install-into-project.sh" --enable-local-hook "$DUMM
 [ -f "$DUMMY/.claude/settings.local.json" ] || fail "hook settings not installed"
 [ ! -d "$DUMMY/scripts" ] || fail "install must not create a scripts folder in the target"
 [ ! -d "$DUMMY/docs" ] || fail "install must not create a docs folder in the target"
+jq -e '.hooks.SessionStart and .hooks.UserPromptSubmit and .hooks.StopFailure' "$DUMMY/.claude/settings.local.json" >/dev/null \
+  || fail "installed local settings missing recovery hooks"
+printf 'ok: installer activated recovery hooks in local settings\n'
+
+step "Existing settings.local should keep settings and receive hooks"
+MERGE_DUMMY="$WORK/merge-repo"
+mkdir -p "$MERGE_DUMMY/.claude"
+printf '{"permissions":{"allow":["Bash(npm test *)"]},"hooks":{"PostToolUse":[{"matcher":"Write","hooks":[{"type":"command","command":"true"}]}]}}\n' \
+  > "$MERGE_DUMMY/.claude/settings.local.json"
+bash "$TEMPLATE_ROOT/scripts/install-into-project.sh" "$MERGE_DUMMY" >/dev/null
+jq -e '
+  (.permissions.allow[0] == "Bash(npm test *)") and
+  (.hooks.PostToolUse[0].matcher == "Write") and
+  (.hooks.SessionStart | length > 0) and
+  (.hooks.UserPromptSubmit | length > 0) and
+  (.hooks.StopFailure | length > 0)
+' "$MERGE_DUMMY/.claude/settings.local.json" >/dev/null || fail "bash installer did not merge hooks into existing settings"
+bash "$TEMPLATE_ROOT/scripts/install-into-project.sh" "$MERGE_DUMMY" >/dev/null
+DUPES=$(jq '[.hooks.SessionStart[], .hooks.UserPromptSubmit[], .hooks.StopFailure[]] | length' "$MERGE_DUMMY/.claude/settings.local.json")
+[ "$DUPES" -eq 3 ] || fail "bash installer duplicated recovery hooks on rerun"
+printf 'ok: bash installer preserved existing settings and merged hooks once\n'
+
+step "Older shell-form recovery hooks should not be duplicated"
+OLD_DUMMY="$WORK/old-hook-repo"
+mkdir -p "$OLD_DUMMY/.claude"
+jq -n '{
+  hooks: {
+    SessionStart: [
+      {
+        hooks: [
+          {
+            type: "command",
+            command: "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/inject-standing-instructions.sh"
+          }
+        ]
+      }
+    ]
+  }
+}' > "$OLD_DUMMY/.claude/settings.local.json"
+bash "$TEMPLATE_ROOT/scripts/install-into-project.sh" "$OLD_DUMMY" >/dev/null
+SESSION_START_COUNT=$(jq '.hooks.SessionStart | length' "$OLD_DUMMY/.claude/settings.local.json")
+[ "$SESSION_START_COUNT" -eq 1 ] || fail "installer duplicated old SessionStart recovery hook"
+jq -e '(.hooks.UserPromptSubmit | length > 0) and (.hooks.StopFailure | length > 0)' \
+  "$OLD_DUMMY/.claude/settings.local.json" >/dev/null || fail "installer failed to add missing hooks next to old hook"
+printf 'ok: installer recognized old recovery hook commands and added only missing hooks\n'
+
+step "Node installer should also merge existing settings.local"
+NODE_DUMMY="$WORK/node-merge-repo"
+mkdir -p "$NODE_DUMMY/.claude"
+printf '{"permissions":{"allow":["Bash(npm test *)"]}}\n' > "$NODE_DUMMY/.claude/settings.local.json"
+node "$TEMPLATE_ROOT/bin/cli.js" init "$NODE_DUMMY" >/dev/null
+jq -e '
+  (.permissions.allow[0] == "Bash(npm test *)") and
+  (.hooks.SessionStart | length > 0) and
+  (.hooks.UserPromptSubmit | length > 0) and
+  (.hooks.StopFailure | length > 0)
+' "$NODE_DUMMY/.claude/settings.local.json" >/dev/null || fail "node installer did not merge hooks into existing settings"
+node "$TEMPLATE_ROOT/bin/cli.js" init "$NODE_DUMMY" >/dev/null
+DUPES=$(jq '[.hooks.SessionStart[], .hooks.UserPromptSubmit[], .hooks.StopFailure[]] | length' "$NODE_DUMMY/.claude/settings.local.json")
+[ "$DUPES" -eq 3 ] || fail "node installer duplicated recovery hooks on rerun"
+printf 'ok: node installer preserved existing settings and merged hooks once\n'
 
 step "Fake SessionStart: standing instructions should be injected"
 INJECTED=$(printf '{"session_id":"fake-session-123","hook_event_name":"SessionStart","source":"startup"}' \
@@ -60,13 +121,15 @@ printf '{"workspace":{"project_dir":"%s"},"model":{"display_name":"Test"},"rate_
 printf 'ok: status line wrapper cached the reset time\n'
 
 step "Fake quota stop: StopFailure(rate_limit) should log and write the marker"
-printf '{"session_id":"fake-session-123","hook_event_name":"StopFailure","error_type":"rate_limit"}' \
+printf '{"session_id":"fake-session-123","hook_event_name":"StopFailure","error":"rate_limit","last_assistant_message":"API Error: Rate limit reached"}' \
   | CLAUDE_PROJECT_DIR="$DUMMY" bash "$DUMMY/.claude/hooks/log-stop-failure.sh"
 [ -f "$DUMMY/.claude/stop-failure-events.jsonl" ] || fail "missing stop-failure log"
 [ -f "$DUMMY/.claude/quota-blocked.json" ] || fail "missing quota-blocked marker"
 grep -Fq "hit a rate limit" "$DUMMY/HANDOFF.md" || fail "missing handoff note"
 SESSION=$(jq -r '.hook_input.session_id // empty' "$DUMMY/.claude/quota-blocked.json")
 [ "$SESSION" = "fake-session-123" ] || fail "marker has wrong session_id: $SESSION"
+ERROR=$(jq -r '.hook_input.error // empty' "$DUMMY/.claude/quota-blocked.json")
+[ "$ERROR" = "rate_limit" ] || fail "marker has wrong error field: $ERROR"
 RESETS=$(jq -r '.rate_limit_state.five_hour_resets_at // empty' "$DUMMY/.claude/quota-blocked.json")
 [ -n "$RESETS" ] || fail "marker missing cached reset time"
 printf 'ok: hook wrote log, handoff note, and marker with session_id and reset time\n'

package/scripts/verify-claude-loop-workflow.sh

@@ -25,6 +25,7 @@ require_file "HANDOFF.md"
 require_file ".claude/settings.example.json"
 require_file ".claude/hooks/log-stop-failure.sh"
 require_file ".claude/hooks/inject-standing-instructions.sh"
+require_file ".claude/hooks/remind-on-prompt.sh"
 require_file ".claude/standing-instructions.md"
 require_file "scripts/test-fake-quota-flow.sh"
 require_file "README.md"
@@ -62,6 +63,10 @@ require_text ".claude/settings.example.json" "SessionStart"
 require_text ".claude/settings.example.json" "inject-standing-instructions.sh"
 require_text ".claude/standing-instructions.md" "auto-continue.md"
 require_text ".claude/standing-instructions.md" "HANDOFF.md"
+require_text ".claude/settings.example.json" "UserPromptSubmit"
+require_text ".claude/settings.example.json" "remind-on-prompt.sh"
+require_text ".claude/hooks/remind-on-prompt.sh" "HANDOFF.md"
+require_text ".claude/hooks/remind-on-prompt.sh" "auto-continue.md"
 require_text ".claude/settings.example.json" "StopFailure"
 require_text ".claude/settings.example.json" "rate_limit"
 require_text ".claude/settings.example.json" "log-stop-failure.sh"
@@ -78,6 +83,7 @@ require_text "scripts/quota-watcher.sh" "session_id"
 [ -x "$ROOT/scripts/install-into-project.sh" ] || fail "scripts/install-into-project.sh must be executable"
 [ -x "$ROOT/scripts/quota-watcher.sh" ] || fail "scripts/quota-watcher.sh must be executable"
 [ -x "$ROOT/.claude/hooks/inject-standing-instructions.sh" ] || fail ".claude/hooks/inject-standing-instructions.sh must be executable"
+[ -x "$ROOT/.claude/hooks/remind-on-prompt.sh" ] || fail ".claude/hooks/remind-on-prompt.sh must be executable"
 [ -x "$ROOT/scripts/test-fake-quota-flow.sh" ] || fail "scripts/test-fake-quota-flow.sh must be executable"
 
 for forbidden in "claude -p" "tmux" "screen" "expect" "TIOCSTI"; do