@ccoalm/ccl-skills 0.18.10 → 0.18.12

package/dist/assets/marketplace/plugins/ccl-skills/hooks/headless-background-stop.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Stop guard for sessions nothing re-invokes (claude -p, the SDKs): one block per background
+# task still running at the stop, because the host stops those tasks when the session ends and
+# work waiting on them is lost. Interactive sessions exit here untouched. Reads only the hook
+# input, never the transcript or host configuration.
+set -u
+case "${CLAUDE_CODE_ENTRYPOINT:-}" in
+  sdk|sdk-*) ;;
+  *) exit 0 ;;
+esac
+HELPER="$(cd "$(dirname "$0")" && pwd)/host-input.py"
+if ! command -v python3 >/dev/null 2>&1 || [ ! -r "$HELPER" ]; then
+  printf '%s\n' '{"systemMessage":"Background task check unavailable: Python input normalizer missing."}'
+  exit 0
+fi
+python3 "$HELPER" headless-background 2>/dev/null ||
+  printf '%s\n' '{"systemMessage":"Background task check unavailable: input normalizer failed."}'
+exit 0

package/dist/assets/marketplace/plugins/ccl-skills/hooks/hooks.json

@@ -161,6 +161,13 @@
             "timeout": 5,
             "async": false,
             "statusMessage": "Checking delivery handoff..."
+          },
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/headless-background-stop.sh\"",
+            "timeout": 5,
+            "async": false,
+            "statusMessage": "Checking background tasks..."
           }
         ]
       }

package/dist/assets/marketplace/plugins/ccl-skills/hooks/host-input.py

@@ -579,8 +579,8 @@ def machine_artifact(text):
     return False
 
 
-def stop_notice(payload, lane, message):
-    """Cap notice attempts only; these markers never establish verification."""
+def claim_notice(payload, lane):
+    """True on this lane's first attempt, False on a repeat, None when state is unavailable."""
     try:
         # Reuse the installed runtime's owned-directory/no-follow/atomic claim
         # protections. Minimal vendored runtimes may omit this optional helper.
@@ -596,17 +596,81 @@ def stop_notice(payload, lane, message):
         info = module.regular_info(path)
         state = module.State(key)
         try:
-            if not state.claim_attempt('stop-notice-' + lane, [info.st_dev, info.st_ino]):
-                return None
+            return bool(state.claim_attempt('stop-notice-' + lane, [info.st_dev, info.st_ino]))
         finally:
             state.close()
     except Exception:
-        # Missing identity, a broken optional helper or unsafe/unavailable state
-        # must not invent success. This boundary only controls advisory output.
-        pass
+        return None
+
+
+def stop_notice(payload, lane, message):
+    """Cap notice attempts only; these markers never establish verification."""
+    # Missing identity, a broken optional helper or unsafe/unavailable state must
+    # not invent success: the notice still shows. This only controls advisory output.
+    if claim_notice(payload, lane) is False:
+        return None
     return {'systemMessage': message}
 
 
+# Claude Code reports `sdk-cli` for `claude -p` and an `sdk` entrypoint for the SDKs; interactive
+# sessions report other values and are re-invoked when a background task finishes.
+NON_INTERACTIVE_ENTRYPOINT = re.compile(r'sdk(?:-[a-z]+)?')
+
+
+def claim_background_notice(payload, task_id):
+    """True the first time this session stops with the task still running, False on a repeat,
+    None when state is unavailable. Keyed by session, not transcript, which may not exist."""
+    try:
+        source = Path(__file__).resolve().with_name('skill-loading.py')
+        spec = importlib.util.spec_from_file_location('ccl_stop_state', source)
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        session = payload.get('session_id')
+        if not isinstance(session, str) or not session or len(session) > 1024:
+            return None
+        state = module.State(module.digest([str(module.ROOT), session, 'headless-background']))
+        try:
+            return bool(state.claim_attempt('headless-background', [task_id]))
+        finally:
+            state.close()
+    except Exception:
+        return None
+
+
+def headless_background(payload):
+    """Block a stop once per background task still running in a session nothing re-invokes; the
+    caller has already checked that the entrypoint is one (NON_INTERACTIVE_ENTRYPOINT).
+
+    A headless session ends at the stop and the host stops its background tasks seconds later,
+    so work waiting on their results is lost. Reads only the hook input, so it also works when
+    session persistence is off and the transcript-reading hooks cannot run."""
+    if not isinstance(payload, dict) or payload.get('hook_event_name') != 'Stop':
+        return None
+    tasks = payload.get('background_tasks')
+    running = [task for task in tasks if isinstance(task, dict) and task.get('status') == 'running'
+               and isinstance(task.get('id'), str) and 0 < len(task['id']) <= 128] if isinstance(tasks, list) else []
+    fresh = []
+    for task in running:
+        claimed = claim_background_notice(payload, task['id'])
+        # Without state a repeat cannot be told apart, so the host's own retry flag bounds it.
+        if claimed or (claimed is None and payload.get('stop_hook_active') is False):
+            fresh.append(task)
+    if not fresh:
+        return None
+    def label(task):
+        text = re.sub(r'\s+', ' ', str(task.get('description') or task.get('type') or 'task')).strip()
+        return f'- {text[:100]} ({task["id"]})'
+    listed = [label(task) for task in fresh[:5]] + ([f'- and {len(fresh) - 5} more'] if len(fresh) > 5 else [])
+    return {'decision': 'block', 'reason': (
+        'Background task check: this is a headless session. When you stop, the session ends and these '
+        'background tasks are stopped within seconds, with no notification afterwards:\n' + '\n'.join(listed) +
+        '\nIf the request still depends on one of them, wait for that task in the foreground: poll its output '
+        'file, or the files it writes, in a bounded foreground loop until it has finished, then act on its '
+        'result. Do not start it again; a second run would repeat its effects. If none is needed, stop it with '
+        'TaskStop or say why it can be dropped. '
+        'This check fires once per task.')}
+
+
 def extraction_overflow(payload):
     path = payload.get('transcript_path')
     cwd = payload.get('cwd')
@@ -721,6 +785,75 @@ def doc_closeout_note(payload):
             'the substance stays as the owning skill decided.'.format(names))
 
 
+# Every request re-reads the whole context, so a long session's token cost grows
+# with its size, and a 1M-token window compacts only near its limit by default.
+# The notice goes to the user only (systemMessage, never the model's context),
+# once per band per transcript, and reads just the transcript tail.
+CONTEXT_BANDS = (300000, 600000)
+CONTEXT_TAIL_BYTES = 1024 * 1024
+
+
+def last_context_tokens(path):
+    """Context size of the latest real Claude request, or None when unknown."""
+    descriptor = os.open(path, os.O_RDONLY | os.O_NONBLOCK)
+    with os.fdopen(descriptor, 'rb') as stream:
+        metadata = os.fstat(stream.fileno())
+        if not stat.S_ISREG(metadata.st_mode):
+            return None
+        stream.seek(max(0, metadata.st_size - CONTEXT_TAIL_BYTES))
+        tail = stream.read(CONTEXT_TAIL_BYTES)
+    for line in reversed(tail.split(b'\n')):
+        if b'"usage"' not in line:
+            continue
+        try:
+            event = json.loads(line)
+        except ValueError:
+            continue
+        if not isinstance(event, dict) or event.get('type') != 'assistant' or event.get('isSidechain'):
+            continue
+        message = event.get('message')
+        usage = message.get('usage') if isinstance(message, dict) else None
+        if not isinstance(usage, dict):
+            continue
+        total = 0
+        for key in ('input_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens'):
+            value = usage.get(key)
+            if isinstance(value, int) and not isinstance(value, bool) and value > 0:
+                total += value
+        if total:
+            return total
+    return None
+
+
+def context_notice(payload):
+    path = payload.get('transcript_path')
+    if not isinstance(path, str) or not path:
+        return None
+    tokens = last_context_tokens(path)
+    reached = [band for band in CONTEXT_BANDS if tokens is not None and tokens >= band]
+    if not reached:
+        return None
+    message = ('本会话上下文约 {} 万 token：之后每次请求都会重读这些内容，长会话的 token 主要花在这里。'
+               '当前交付收口后可先写好交接再 /clear 开新会话；或用 /autocompact 把自动压缩提前'
+               '（如 /autocompact 400k）。此提示只显示给你，不影响当前任务。').format(tokens // 10000)
+    # Optional information: without the state helper it stays quiet rather than
+    # repeating on every stop.
+    return message if claim_notice(payload, 'context-{}k'.format(reached[-1] // 1000)) is True else None
+
+
+def with_context_notice(payload, result):
+    try:
+        notice = context_notice(payload) if isinstance(payload, dict) else None
+    except Exception:  # advisory: a failed size check never costs another notice
+        notice = None
+    if not notice:
+        return result
+    result = dict(result or {})
+    result['systemMessage'] = (result['systemMessage'] + '\n' + notice
+                               if result.get('systemMessage') else notice)
+    return result
+
+
 def proposed_next(payload):
     if (not isinstance(payload, dict) or payload.get('hook_event_name') != 'Stop'
             or payload.get('stop_hook_active') is not False):
@@ -810,6 +943,18 @@ def main():
                               'verifiable': False, 'truncated': True, 'prior_handoff': False,
                               'continuation_contract_visible': False}))
             return 1
+    elif sys.argv[1] == 'headless-background':
+        if not NON_INTERACTIVE_ENTRYPOINT.fullmatch(os.environ.get('CLAUDE_CODE_ENTRYPOINT', '')):
+            return 0  # an interactive session hears nothing from this check, whatever its input
+        try:
+            raw = sys.stdin.read(2 * 1024 * 1024 + 1)
+            if len(raw) > 2 * 1024 * 1024:
+                raise ValueError('oversized input')
+            result = headless_background(json.loads(raw))
+            if result:
+                print(json.dumps(result))
+        except (OSError, ValueError, TypeError, IndexError, AttributeError):
+            print(json.dumps({'systemMessage': 'Background task check unavailable: input could not be verified.'}))
     elif sys.argv[1] in ('proposed-next', 'extraction-overflow'):
         payload = {}
         try:
@@ -818,12 +963,14 @@ def main():
                 raise ValueError('oversized input')
             payload = json.loads(raw)
             result = (extraction_overflow(payload) if sys.argv[1] == 'extraction-overflow'
-                      else proposed_next(payload))
+                      else with_context_notice(payload, proposed_next(payload)))
             if result:
                 print(json.dumps(result))
         except TranscriptTruncated:
             result = stop_notice(payload, 'handoff-overflow',
                                  'Delivery handoff reminder unverified: transcript scan exceeded its bounded limit.')
+            if sys.argv[1] == 'proposed-next':
+                result = with_context_notice(payload, result)
             if result:
                 print(json.dumps(result))
         except (OSError, ValueError, TypeError, IndexError, AttributeError):

package/dist/assets/marketplace/plugins/ccl-skills/hooks/remind-post-merge-cleanup.sh

@@ -70,8 +70,9 @@ masked=$(printf '%s' "$cmd" | sed -E \
 # `-f body=` values, echoed docs, `git log --grep`), and an advisory that cries
 # wolf gets ignored. Raw-API / GraphQL / curl merges are an ACCEPTED best-effort
 # NON-fire — `glab mr merge` / `gh pr merge` is the near-universal agent merge
-# path, and the human-readable cleanup rule in worktree-isolation SKILL.md +
-# bootstrap covers EVERY merge path regardless of this reminder.
+# path, and the human-readable cleanup rule in worktree-isolation
+# references/merge-and-teardown.md + bootstrap covers EVERY merge path
+# regardless of this reminder.
 # `gh help pr merge` / `glab help mr merge` print help (the merge guard's help
 # denial points there). Remove only those literal invocations, never a prefix,
 # so a real merge before or after them in the same command still matches.
@@ -129,12 +130,16 @@ if command -v git >/dev/null 2>&1 && git -C "$cwd" rev-parse --git-dir >/dev/nul
   wt=$(git -C "$cwd" worktree list 2>/dev/null)
 fi
 
-reminder="🧹 worktree-isolation 收尾提醒（自动）：检测到 MR/PR 合并命令。先按本节「已集成判据」确认这次合并**已真正完成**（平台 MR/PR 已在当前 head SHA 上 merged；仅授权、仅排队 auto-merge、或合并失败都不算已集成）；确认后，若源分支是临时 feature 分支就立即清理三侧，别攒：
+# The text points at the canonical teardown section and carries the guards that
+# must not be lost at this moment; a digest that drops any of them would
+# out-vote the canonical rule the agent loaded earlier.
+reminder="🧹 worktree-isolation 收尾提醒（自动）：检测到 MR/PR 合并命令。动手前先读 worktree-isolation/references/merge-and-teardown.md 的「收尾」节，按其「已集成判据」确认这次合并**已真正完成**（平台 MR/PR 已在当前 head SHA 上 merged；仅授权、仅排队 auto-merge、或合并失败都不算已集成）；确认后，若源分支是临时 feature 分支就立即清理三侧，别攒：
+  git -C <path> status --ignored -s  # 删 worktree 前必须先跑且必须 exit 0；非空先按重算代价判定，贵的产物先救回主检出
   git worktree remove <path>        # 不加 --force（脏树/未合并被拒=安全网）
   git branch -d <branch>            # 不加 -D（未合并被拒=安全网）
   git push origin --delete <branch> # 远端源分支——破坏性，务必先确认已集成再删
   git worktree prune && git worktree list && git branch   # 验证三侧都没了
-唯一例外：源分支本身是永久/集成分支（如 dev→main promotion，源是 dev）——绝不删。squash 合并测不到祖先则保守保留、先确认已集成。"
+不删的例外：① 源分支本身是永久/集成分支（如 dev→main promotion，源是 dev）；② 分支名含 release 的分支（大小写不敏感，如 release/*、hotfix-release），要删由用户显式指名。squash 合并测不到祖先则保守保留、先确认已集成；worktree 里仍有未完成的外部副作用任务（迁移/部署等）时，等它完成再清。"
 if [ -n "$wt" ]; then
   reminder="${reminder}
 当前 worktrees（挑出刚合并的那个源 worktree 清理）：

package/dist/assets/marketplace/plugins/ccl-skills/hooks/task-entry.sh

@@ -1,15 +1,36 @@
 #!/usr/bin/env bash
-# Deliver the canonical task entry before sampling, without inspecting the prompt.
+# Deliver the canonical task entry before sampling. The prompt is never classified
+# or echoed. One structural check spots a prompt that is exactly one
+# <task-notification> envelope, the turn the host starts itself to deliver a
+# background completion: that turn keeps the skill-loading and unfinished-work
+# boundary but not the routing list, which SessionStart already keeps in context.
 SCRIPT_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
 if ! command -v python3 >/dev/null 2>&1; then
   printf 'ccl-skills task-entry: python3 unavailable; task entry omitted\n' >&2
   printf '{}\n'
   exit 0
 fi
-python3 - "$SCRIPT_DIR/../agent-context/session-start.md" <<'PY'
+# fd 3 carries the hook input; stdin is the heredoc program. A closed stdin reads
+# as empty input, which keeps the entry.
+if ! { : 3<&0; } 2>/dev/null; then exec 0</dev/null; fi
+python3 - "$SCRIPT_DIR/../agent-context/session-start.md" 3<&0 <<'PY'
 import json
+import os
 import sys
 
+host_turn = False
+try:
+    with os.fdopen(3, 'rb') as hook_input:
+        raw = hook_input.read(1048577)
+    payload = json.loads(raw) if len(raw) <= 1048576 else None
+    prompt = payload.get('prompt') if isinstance(payload, dict) else None
+    envelope = prompt.strip() if isinstance(prompt, str) else ''
+    host_turn = (envelope.startswith('<task-notification>') and envelope.endswith('</task-notification>')
+                 and envelope.count('<task-notification>') == 1 and envelope.count('</task-notification>') == 1)
+except (OSError, ValueError, RecursionError):
+    # Unreadable input keeps the full entry: trimming is only for a proven host turn.
+    host_turn = False
+
 try:
     with open(sys.argv[1], 'rb') as stream:
         raw = stream.read(32769)
@@ -35,7 +56,7 @@ try:
                 'Inspect failure evidence, research or change the approach, repair safely and rerun the relevant checks. '
                 'A report alone does not complete it. Continue available authorized work; hand back only for a '
                 'required user decision or unavailable authority/resource, stating the concrete blocker.\n\n')
-    context = '<ccl-task-entry>\n' + boundary + entry + '\n</ccl-task-entry>'
+    context = '<ccl-task-entry>\n' + (boundary.rstrip('\n') if host_turn else boundary + entry) + '\n</ccl-task-entry>'
     if len(context.encode('utf-8')) > 4096:
         raise ValueError('oversized entry')
     print(json.dumps({'hookSpecificOutput': {

package/dist/assets/marketplace/plugins/ccl-skills/hooks/test_headless_background_stop.sh

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+# Deterministic behavior suite for hooks/headless-background-stop.sh.
+# Registered in the Makefile `test` target; requires jq to build hook inputs.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+HOOK="${HEADLESS_BG_HOOK:-$SCRIPT_DIR/headless-background-stop.sh}"
+[ -f "$HOOK" ] || { echo "FAIL: hook not found: $HOOK" >&2; exit 1; }
+command -v jq >/dev/null 2>&1 || { echo "FAIL: jq required for this suite" >&2; exit 1; }
+bash -n "$HOOK" || { echo "FAIL: hook is not syntactically valid" >&2; exit 1; }
+
+pass=0; fail=0
+WORK="$(mktemp -d "${TMPDIR:-/tmp}/headless-bg-test.XXXXXX")"
+trap 'rm -rf "$WORK"' EXIT
+STATE="$WORK/state"; mkdir -p "$STATE"
+ERR="$WORK/err"
+
+# payload <session> <stop_hook_active> <tasks-json>
+payload() {
+  jq -nc --arg s "$1" --argjson a "$2" --argjson t "$3" \
+    '{session_id:$s,hook_event_name:"Stop",stop_hook_active:$a,background_tasks:$t}'
+}
+task() {  # task <id> <status> [description]
+  jq -nc --arg i "$1" --arg st "$2" --arg d "${3:-Run the review gate}" \
+    '{id:$i,type:"shell",status:$st,description:$d,command:"sleep 60"}'
+}
+
+# run <entrypoint> <tmpdir> <stdin> -> sets OUT; fails the case unless exit 0 with silent stderr
+run() {
+  local rc errbytes
+  OUT=$(printf '%s' "$3" | CLAUDE_CODE_ENTRYPOINT="$1" TMPDIR="$2" bash "$HOOK" 2>"$ERR"); rc=$?
+  errbytes=$(wc -c <"$ERR" | tr -d ' ')
+  [ "$rc" = 0 ] && [ "$errbytes" = 0 ] && return 0
+  echo "FAIL: hook must exit 0 with silent stderr (rc=$rc, stderr=${errbytes}B)"; fail=$((fail + 1)); return 1
+}
+
+# expect <block|quiet|notice> <label> <entrypoint> <tmpdir> <stdin> [needle...]
+expect() {
+  local want="$1" label="$2" got needle
+  run "$3" "$4" "$5" || return
+  if [ -z "$OUT" ]; then
+    got=quiet
+  elif printf '%s' "$OUT" | jq -e '.decision == "block" and (.reason | type == "string")' >/dev/null 2>&1; then
+    got=block
+  elif printf '%s' "$OUT" | jq -e '.systemMessage | startswith("Background task check unavailable")' >/dev/null 2>&1; then
+    got=notice
+  else
+    echo "FAIL [$label]: unexpected output: $OUT"; fail=$((fail + 1)); return
+  fi
+  if [ "$got" != "$want" ]; then
+    echo "FAIL [$label]: expected $want, got $got: $OUT"; fail=$((fail + 1)); return
+  fi
+  shift 5
+  for needle in "$@"; do
+    if ! printf '%s' "$OUT" | jq -e --arg n "$needle" '.reason | contains($n)' >/dev/null 2>&1; then
+      echo "FAIL [$label]: reason lacks '$needle': $OUT"; fail=$((fail + 1)); return
+    fi
+  done
+  pass=$((pass + 1))
+}
+
+one="[$(task t1 running 'Run the external review on the diff')]"
+expect block "headless stop with a running task" sdk-cli "$STATE" "$(payload s1 false "$one")" \
+  "headless session" "Run the external review on the diff (t1)" "foreground" "Do not start it again" "TaskStop" "once per task"
+if printf '%s' "$OUT" | jq -e '.reason | test("(?i)run(ning)? it again|rerun")' >/dev/null 2>&1; then
+  echo "FAIL [headless stop with a running task]: the reason advises starting the task again"; fail=$((fail + 1))
+fi
+expect quiet "the same task at the next stop" sdk-cli "$STATE" "$(payload s1 true "$one")"
+expect quiet "the same task without the host retry flag" sdk-cli "$STATE" "$(payload s1 false "$one")"
+both="[$(task t1 running),$(task t2 running 'Wait for the lane')]"
+expect block "a new task in the same session" sdk-cli "$STATE" "$(payload s1 true "$both")" "Wait for the lane (t2)"
+if printf '%s' "$OUT" | jq -e '.reason | contains("(t1)")' >/dev/null 2>&1; then
+  echo "FAIL [a new task in the same session]: an already reported task was listed again"; fail=$((fail + 1))
+fi
+expect block "another session with the same task id" sdk-cli "$STATE" "$(payload s2 false "$one")" "(t1)"
+expect block "an SDK entrypoint" sdk-py "$STATE" "$(payload s3 false "$one")" "(t1)"
+
+expect quiet "an interactive session" cli "$STATE" "$(payload s4 false "$one")"
+expect quiet "no entrypoint" "" "$STATE" "$(payload s4 false "$one")"
+expect quiet "a lookalike entrypoint" sdkx "$STATE" "$(payload s4 false "$one")"
+done_task="[$(task t9 completed)]"
+expect quiet "no task still running" sdk-cli "$STATE" "$(payload s5 false "$done_task")"
+expect quiet "no background tasks field" sdk-cli "$STATE" '{"session_id":"s5","hook_event_name":"Stop","stop_hook_active":false}'
+expect quiet "another hook event" sdk-cli "$STATE" "$(jq -nc --argjson t "$one" '{session_id:"s5",hook_event_name:"SubagentStop",stop_hook_active:false,background_tasks:$t}')"
+expect notice "input that is not JSON" sdk-cli "$STATE" 'not json'
+
+# Without usable state a repeat cannot be recognized, so the host retry flag bounds it.
+expect block "no state, first stop" sdk-cli "$WORK/missing/dir" "$(payload s6 false "$one")" "(t1)"
+expect quiet "no state, host retry" sdk-cli "$WORK/missing/dir" "$(payload s6 true "$one")"
+
+# The helper repeats the entrypoint check, so it holds even when called without the wrapper.
+HELPER="$(dirname "$HOOK")/host-input.py"
+helper_quiet() {  # helper_quiet <label> <entrypoint>
+  local out
+  out=$(printf '%s' "$(payload s9 false "$one")" | CLAUDE_CODE_ENTRYPOINT="$2" TMPDIR="$STATE" python3 "$HELPER" headless-background 2>"$ERR")
+  if [ -z "$out" ] && [ ! -s "$ERR" ]; then pass=$((pass + 1)); else echo "FAIL [$1]: helper spoke: $out"; fail=$((fail + 1)); fi
+}
+helper_quiet "the helper alone in an interactive session" cli
+helper_quiet "the helper alone with a lookalike entrypoint" sdkx
+out=$(printf 'not json' | CLAUDE_CODE_ENTRYPOINT=cli TMPDIR="$STATE" python3 "$HELPER" headless-background 2>"$ERR")
+if [ -z "$out" ] && [ ! -s "$ERR" ]; then pass=$((pass + 1)); else echo "FAIL [the helper alone, interactive, bad input]: $out"; fail=$((fail + 1)); fi
+
+# The wrapper leaves interactive sessions before the helper: no Python start, no notice about it.
+BASH_BIN="$(command -v bash)"; mkdir -p "$WORK/no-python"; ln -s "$(command -v dirname)" "$WORK/no-python/dirname"
+no_python() {  # no_python <label> <entrypoint> <expected output or empty>
+  local out
+  out=$(printf '%s' "$(payload s10 false "$one")" | CLAUDE_CODE_ENTRYPOINT="$2" PATH="$WORK/no-python" "$BASH_BIN" "$HOOK" 2>"$ERR")
+  if [ "$out" = "$3" ] && [ ! -s "$ERR" ]; then pass=$((pass + 1)); else echo "FAIL [$1]: got '$out'"; fail=$((fail + 1)); fi
+}
+no_python "an interactive session without Python" cli ""
+no_python "a headless session without Python" sdk-cli \
+  '{"systemMessage":"Background task check unavailable: Python input normalizer missing."}'
+
+many="[$(for i in 1 2 3 4 5 6 7; do task "m$i" running; printf ','; done | sed 's/,$//')]"
+expect block "a long task list" sdk-cli "$STATE" "$(payload s7 false "$many")" "(m5)" "and 2 more"
+if printf '%s' "$OUT" | jq -e '.reason | test("\\(m[67]\\)")' >/dev/null 2>&1; then
+  echo "FAIL [a long task list]: a task beyond the first five was listed"; fail=$((fail + 1))
+fi
+hundred=$(printf 'x%.0s' $(seq 100))
+long="[$(task c1 running "${hundred}yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy")]"
+expect block "a long description" sdk-cli "$STATE" "$(payload s11 false "$long")" "${hundred} (c1)"
+
+# Identifiers from the input never name a path: hostile ones stay inside the state root.
+hostile="[$(task '../../../evil-task' running)]"
+expect block "hostile identifiers, first stop" sdk-cli "$STATE" "$(payload '../../escape' false "$hostile")" "(../../../evil-task)"
+expect quiet "hostile identifiers, next stop" sdk-cli "$STATE" "$(payload '../../escape' false "$hostile")"
+if find "$WORK" -name '*evil*' -o -name '*escape*' | grep -q .; then
+  echo "FAIL [hostile identifiers]: an input identifier became a path"; fail=$((fail + 1))
+else pass=$((pass + 1)); fi
+
+# Two stops racing for the same new task: the claim is atomic, so exactly one blocks.
+race="$(payload race false "[$(task r1 running)]")"
+for i in 1 2 3 4; do
+  (printf '%s' "$race" | CLAUDE_CODE_ENTRYPOINT=sdk-cli TMPDIR="$STATE" bash "$HOOK" > "$WORK/race.$i" 2>/dev/null) &
+done
+wait
+blocks=$(cat "$WORK"/race.* | grep -c '"decision": "block"')
+if [ "$blocks" = 1 ]; then pass=$((pass + 1)); else echo "FAIL [racing stops]: $blocks blocks for one task"; fail=$((fail + 1)); fi
+
+# A state root that is a symlink is refused, so the guard falls back to the host retry flag.
+mkdir -p "$WORK/sym" "$WORK/elsewhere"; ln -s "$WORK/elsewhere" "$WORK/sym/ccl-skill-loading-$(id -u)"
+expect block "symlinked state root, first stop" sdk-cli "$WORK/sym" "$(payload s12 false "$one")" "(t1)"
+expect quiet "symlinked state root, host retry" sdk-cli "$WORK/sym" "$(payload s12 true "$one")"
+if [ -z "$(ls -A "$WORK/elsewhere")" ]; then pass=$((pass + 1)); else echo "FAIL [symlinked state root]: state written through the link"; fail=$((fail + 1)); fi
+multiline="[$(task n1 running "$(printf 'line one\nline two')")]"
+expect block "a description with a line break" sdk-cli "$STATE" "$(payload s8 false "$multiline")" "line one line two (n1)"
+
+echo "pass=$pass fail=$fail"
+[ "$fail" = 0 ] || exit 1
+echo "test_headless_background_stop_ok"

package/dist/assets/marketplace/plugins/ccl-skills/hooks/test_proposed_next.py

@@ -541,6 +541,77 @@ class ProposedNextTests(unittest.TestCase):
         (self.hooks / 'host-input.py').unlink()
         self.assertIn('unavailable', self.run_hook().get('systemMessage', ''))
 
+    def usage_event(self, context, cache_read=None, model='claude-opus-5-5'):
+        read = context - 2000 if cache_read is None else cache_read
+        return {'type': 'assistant', 'message': {'model': model, 'content': [{'type': 'text', 'text': 'ok'}],
+                'usage': {'input_tokens': 2, 'cache_read_input_tokens': read,
+                          'cache_creation_input_tokens': context - 2 - read, 'output_tokens': 50}}}
+
+    def run_with_state(self, payload=None):
+        # The once-per-band cap uses the optional state helper; give it a private TMPDIR.
+        shutil.copyfile(ROOT / 'hooks/skill-loading.py', self.hooks / 'skill-loading.py')
+        state = self.root.parent / (self.root.name + '-state')
+        state.mkdir(exist_ok=True)
+        value = self.payload if payload is None else payload
+        result = subprocess.run(['bash', str(self.hooks / 'proposed-next-stop.sh')],
+                                input=json.dumps(value), text=True, capture_output=True, cwd=self.root,
+                                env=dict(os.environ, TMPDIR=str(state)))
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertEqual(result.stderr, '')
+        return json.loads(result.stdout) if result.stdout else {}
+
+    def test_large_context_notice_is_user_only_and_once_per_band(self):
+        self.events([self.usage_event(120000), self.usage_event(299999)])
+        self.assertEqual(self.run_with_state(), {})
+        self.events([self.usage_event(120000), self.usage_event(321000)])
+        first = self.run_with_state()
+        self.assertEqual(set(first), {'systemMessage'})  # shown to the user, never a block or model context
+        self.assertIn('32 万', first['systemMessage'])
+        self.assertIn('/autocompact', first['systemMessage'])
+        self.assertIn('/clear', first['systemMessage'])
+        self.assertEqual(self.run_with_state(), {})  # same band: no repeat
+        self.events([self.usage_event(321000), self.usage_event(612000)])
+        second = self.run_with_state()
+        self.assertIn('61 万', second.get('systemMessage', ''))
+        self.assertEqual(self.run_with_state(), {})
+
+    def test_large_context_notice_stays_quiet_without_its_state_helper(self):
+        # Without the once-per-band record the notice would repeat on every stop, so
+        # it is withheld; notices that must show (handoff overflow) still show.
+        self.events([self.usage_event(450000)])
+        self.assertFalse((self.hooks / 'skill-loading.py').exists())
+        self.assertEqual(self.run_hook(), {})
+        self.assertEqual(self.run_hook(), {})
+
+    def test_large_context_notice_rides_with_a_continuation_reminder(self):
+        self.events([self.usage_event(450000)])
+        payload = dict(self.payload, last_assistant_message='Fixed.\n\nproposed-next: run the integration suite')
+        value = self.run_with_state(payload)
+        self.assertEqual(value.get('decision'), 'block')
+        self.assertIn('proposed-next:', value['reason'])
+        self.assertIn('45 万', value.get('systemMessage', ''))
+        self.assertNotIn('万 token', value['reason'])  # the model-facing reason stays unchanged
+
+    def test_large_context_notice_reads_only_the_latest_real_claude_usage(self):
+        # A trailing zero-usage (synthetic) entry is skipped; Codex shapes and huge
+        # trailing tool output without usage stay quiet; the notice never needs the
+        # bounded full-transcript scan.
+        synthetic = self.usage_event(0, cache_read=0, model='<synthetic>')
+        synthetic['message']['usage'] = {'input_tokens': 0, 'cache_read_input_tokens': 0,
+                                         'cache_creation_input_tokens': 0, 'output_tokens': 0}
+        self.events([self.usage_event(330000), synthetic])
+        self.assertIn('33 万', self.run_with_state().get('systemMessage', ''))
+        self.setUp()
+        self.events([{'type': 'event_msg', 'payload': {'type': 'token_count', 'info': {
+            'last_token_usage': {'input_tokens': 900000}}}}])
+        self.assertEqual(self.run_with_state(), {})
+        self.setUp()
+        self.events([self.usage_event(500000)] + [{'type': 'user', 'text': 'x' * 400000}] * 3)
+        self.assertEqual(self.run_with_state(), {})
+        self.setUp()
+        self.events([{'type': 'ignored'}] * 20000 + [self.usage_event(700000)])
+        self.assertIn('70 万', self.run_with_state().get('systemMessage', ''))
+
     def test_scan_is_bounded_and_no_filesystem_markers_are_written(self):
         self.events([{'type': 'ignored'}] * 20000 + self.claude_load())
         before = set(self.root.rglob('*'))

package/dist/assets/marketplace/plugins/ccl-skills/hooks/test_remind_post_merge_cleanup.sh

@@ -128,6 +128,53 @@ probe remind 'glab mr merge 123 --yes; glab help mr merge' 'Merged !123'
 # a successful-looking string response still reminds
 probe remind 'glab mr merge 123 --yes' 'Merged! https://.../merge_requests/123'
 
+# --- Reminder TEXT contract: the injected text is what the agent acts on right
+#     after the merge, so it must route to the canonical teardown section and
+#     carry the guards a lossy digest once dropped — the ignored-artifact scan
+#     that must exit 0 before any worktree removal, and the release-name branch
+#     exception — instead of claiming a single exception. ---
+reminder_text=$(jq -nc --arg c 'gh pr merge 45 --merge' --arg r 'Merged' \
+  '{tool_input:{command:$c},tool_response:$r,cwd:"/tmp"}' | bash "$HOOK" \
+  | jq -r '.hookSpecificOutput.additionalContext // empty')
+text_has() { # <label> <needle>
+  if printf '%s' "$reminder_text" | grep -Fq -- "$2"; then pass=$((pass+1))
+  else fail=$((fail+1)); printf 'FAIL  [reminder text lacks %s]  %s\n' "$1" "$2" >&2; fi
+}
+text_lacks() { # <label> <needle>
+  if printf '%s' "$reminder_text" | grep -Fq -- "$2"; then
+    fail=$((fail+1)); printf 'FAIL  [reminder text still carries %s]  %s\n' "$1" "$2" >&2
+  else pass=$((pass+1)); fi
+}
+if [ -n "$reminder_text" ]; then pass=$((pass+1))
+else fail=$((fail+1)); echo 'FAIL  [no reminder text extracted]' >&2; fi
+TEARDOWN_REF='worktree-isolation/references/merge-and-teardown.md'
+text_has   'canonical teardown pointer' "$TEARDOWN_REF"
+text_has   'ignored-artifact scan before removal' 'status --ignored -s'
+text_has   'scan exit-0 requirement' '必须 exit 0'
+text_lacks 'single-exception claim' '唯一例外'
+# A guard is its meaning, not one keyword: every needle must sit on the same
+# line, so dropping the "keep" sense while a keyword survives still fails.
+line_has_all() { # <label> <needle>...
+  local label="$1"; shift
+  if printf '%s\n' "$reminder_text" | awk -v n="$#" 'BEGIN{for(i=1;i<=n;i++) want[i]=ARGV[i]; ARGC=1}
+       {hit=1; for(i=1;i<=n;i++) if (index($0, want[i])==0) hit=0; if (hit) found=1}
+       END{exit found?0:1}' "$@"; then pass=$((pass+1))
+  else fail=$((fail+1)); printf 'FAIL  [reminder text lacks %s on one line]\n' "$label" >&2; fi
+}
+line_has_all 'release-name branch kept' '不删的例外' '分支名含 release' '要删由用户显式指名'
+line_has_all 'permanent/integration branch kept' '不删的例外' '源分支本身是永久/集成分支'
+line_has_all 'external-side-effect wait' '未完成的外部副作用任务' '等它完成再清'
+# The scan guards the removal, so it must come first — an order the substring
+# checks above cannot see.
+scan_at=$(printf '%s\n' "$reminder_text" | grep -n -F 'status --ignored -s' | head -1 | cut -d: -f1)
+remove_at=$(printf '%s\n' "$reminder_text" | grep -n -F 'git worktree remove' | head -1 | cut -d: -f1)
+if [ -n "$scan_at" ] && [ -n "$remove_at" ] && [ "$scan_at" -lt "$remove_at" ]; then pass=$((pass+1))
+else fail=$((fail+1)); echo "FAIL  [reminder text lacks scan ordered before removal] scan=${scan_at:-none} remove=${remove_at:-none}" >&2; fi
+# The pointer must resolve: the canonical file exists in this tree and still
+# carries the teardown section heading the pointer names.
+if grep -Fq '## 收尾：' "$SCRIPT_DIR/../skills/$TEARDOWN_REF" 2>/dev/null; then pass=$((pass+1))
+else fail=$((fail+1)); echo "FAIL  [teardown pointer dangles] skills/$TEARDOWN_REF lacks '## 收尾：'" >&2; fi
+
 printf 'remind-post-merge-cleanup tests: pass=%d fail=%d\n' "$pass" "$fail"
 [ "$fail" -eq 0 ] || exit 1
 echo "test_remind_post_merge_cleanup_ok"