@ccoalm/ccl-skills 0.6.1 → 0.7.0

package/README.md

@@ -1,12 +1,16 @@
 # @ccoalm/ccl-skills
 
-Self-contained CCL Skills installer for Claude Code, Codex, and OpenCode. The package carries an immutable snapshot of the skills, agent context, plugin manifests, and runtime hooks, so normal installation does not need a Git checkout. Claude Code and Codex consume their plugin hooks directly; OpenCode installs a native event adapter and the same bundled hook runtime.
+[![npm version](https://img.shields.io/npm/v/@ccoalm/ccl-skills)](https://www.npmjs.com/package/@ccoalm/ccl-skills)
+[![downloads](https://img.shields.io/npm/dm/@ccoalm/ccl-skills)](https://www.npmjs.com/package/@ccoalm/ccl-skills)
+[![license](https://img.shields.io/npm/l/@ccoalm/ccl-skills)](https://github.com/ccoalm/ccl-skills/blob/main/LICENSE)
 
-## Requirements
+**Reusable workflows that help coding agents plan, build, test, review, and release software.**
 
-- Node.js 20 or later
-- At least one supported host CLI: Claude Code, Codex 0.133.0 or later, or OpenCode
-- macOS or Linux
+Not a prompt pack — a routed delivery system. 32 skills cover the whole lifecycle, and a routing layer reads what you asked for and hands it to the skill that owns that deliverable, so you never look one up.
+
+Ask it to fix a bug and `defect-diagnosis` takes over: reproduce from first-hand failure evidence, isolate the cause, verify the fix, leave a regression test behind. Ask for a feature and `product-rd-workflow` routes it through requirement shaping, risk gates, implementation, and release. Ask it to touch code at all and `worktree-isolation` puts the work on its own branch first. Every skill also states when *not* to use it and which one to use instead — that is what keeps the routing sharp.
+
+Each skill is a method, not a suggestion, and it ships with the gate that protects it. The methods are what worked, written down. The gates are what went wrong, turned into a stop: no patch before a reproduction, no edit on `main`, no *done* without evidence. A routing eval bank and CI gates check that both still fire.
 
 ## Install
 
@@ -15,24 +19,50 @@ npm install --global @ccoalm/ccl-skills
 ccl-skills install
 ```
 
-Run without a global install:
+Restart your CLI so it reloads the skills.
+
+`install` configures every host it detects. The package carries an immutable snapshot of the skills, agent context, plugin manifests, and runtime hooks, so installation needs no Git checkout.
+
+Requirements: Node.js 20 or later, macOS or Linux, and at least one host CLI — Claude Code, Codex 0.133.0 or later, or OpenCode.
+
+Run it without a global install:
 
 ```bash
 npx @ccoalm/ccl-skills@latest install
 ```
 
-The CLI detects installed hosts. Limit an operation with `--host claude`, `--host codex`, or `--host opencode`.
+## What you get
+
+| Stage | Covered by the skills |
+| --- | --- |
+| Requirements | intent and acceptance points, current-state baseline, change scope and slicing, PRD writing |
+| Design | layout, interaction, states, accessibility, design-system consistency |
+| Architecture | Go and Python service boundaries, RPC and API contracts, data ownership, reliability invariants |
+| Implementation | Go, Python, React web, mini-programs, Flutter/React Native/iOS/Android, terminal and TUI, LLM integration |
+| Testing | test layers, fixtures, mocks, regression coverage, CI gates, test-case documents, defect diagnosis |
+| Review | independent CLI review, adversarial challenge, risk and gate routing, multi-perspective research |
+| Release | rollout, canary, rollback, environment lanes, release scope and docs |
+| Operations | logs, metrics, tracing, dashboards, alerts, SLO, service connectivity |
+| Cross-stage | worktree isolation, multi-agent delegation, doc tightening, lesson extraction |
+
+[Browse the full catalog](https://github.com/ccoalm/ccl-skills/blob/main/docs/SKILLS.md) for what each skill does and when to use another one instead. [Architecture](https://github.com/ccoalm/ccl-skills/blob/main/docs/ARCHITECTURE.md) explains how skills are selected, loaded, and checked; [Theory](https://github.com/ccoalm/ccl-skills/blob/main/docs/skills-theory-foundations.md) explains why the rules read the way they do.
+
+This page ships inside the published tarball, so it only changes when a new version is released. The links above always show the current state.
+
+## Commands
 
 ```bash
-ccl-skills install --host codex
-ccl-skills doctor
-ccl-skills update
-ccl-skills update --yes
-ccl-skills uninstall
-ccl-skills uninstall --yes
+ccl-skills install           # write host assets
+ccl-skills doctor            # report install state and drift from the manifest
+ccl-skills update            # preview
+ccl-skills update --yes      # upgrade the package, then refresh host assets
+ccl-skills uninstall         # preview
+ccl-skills uninstall --yes   # remove host assets
 ```
 
-`update` and `uninstall` are previews unless `--yes` is supplied. By default, `update --yes` first upgrades the global npm package to `@latest`, then asks the freshly installed CLI to refresh host assets. Set `CCL_SKILLS_SKIP_SELF_UPDATE=1` for an assets-only refresh. `--allow-downgrade` always uses the currently invoked package without installing `@latest` first.
+Limit any operation to one host with `--host claude`, `--host codex`, or `--host opencode`. Add `--json` for machine-readable output.
+
+`update` and `uninstall` are previews unless `--yes` is supplied. `update --yes` first upgrades the global npm package to `@latest`, then asks the freshly installed CLI to refresh host assets. Set `CCL_SKILLS_SKIP_SELF_UPDATE=1` for an assets-only refresh; `--allow-downgrade` always uses the currently invoked package without installing `@latest` first.
 
 After `ccl-skills uninstall --yes`, remove the CLI package itself with `npm uninstall --global @ccoalm/ccl-skills` if it is no longer needed.
 
@@ -48,7 +78,15 @@ Silence: CCL_SKILLS_NO_UPDATE_NOTIFIER=1
 
 The registry check runs at most once every 24 hours in a detached background process, so no invocation waits for the network, and its result is shown by the next run. The notice and its check are both silent under `--json`, in CI, when stdout or stderr is not a terminal, in terminals narrower than 60 columns, and when `CCL_SKILLS_NO_UPDATE_NOTIFIER` or `NO_UPDATE_NOTIFIER` is set. State lives in `version-check.json` under the managed root; a failed check keeps the last known version and never blocks or fails the command.
 
-Claude and Codex use package-owned local marketplace snapshots. OpenCode exposes skills, its native plugin, and `ccl-skills/runtime` through shared host directories. The native adapter maps the shipped session, tool, prompt, subagent, and stop behaviors to OpenCode events and covers `edit`, `write`, and `apply_patch`. Installation refuses unknown collisions, and uninstall preserves shared files for manual cleanup instead of guessing ownership.
+## What lands where
+
+| Host | What the installer writes |
+| --- | --- |
+| Claude Code | A package-owned local marketplace snapshot; the plugin hooks are consumed directly. |
+| Codex | The same package-owned local marketplace snapshot. |
+| OpenCode | Skills, a native event plugin, and `ccl-skills/runtime` under shared host directories. The adapter maps the shipped session, tool, prompt, subagent, and stop behaviors to OpenCode events and covers `edit`, `write`, and `apply_patch`. |
+
+Installation refuses unknown collisions, and uninstall preserves shared files for manual cleanup instead of guessing ownership.
 
 Set `CCL_SKILLS_REPO` to a valid checkout to override only the OpenCode asset source. An invalid override fails before writing host files. Without the variable, installation is offline after npm has downloaded the package.
 
@@ -59,3 +97,5 @@ npm ci
 npm test
 npm run test:pack
 ```
+
+Issues and pull requests go to [ccoalm/ccl-skills](https://github.com/ccoalm/ccl-skills); see [CONTRIBUTING](https://github.com/ccoalm/ccl-skills/blob/main/docs/CONTRIBUTING.md).

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

@@ -47,6 +47,17 @@
           }
         ]
       },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/remind-unverified-cli-flag.sh\"",
+            "timeout": 10,
+            "async": false
+          }
+        ]
+      },
       {
         "matcher": "Task|Agent",
         "hooks": [

package/dist/assets/marketplace/plugins/ccl-skills/hooks/remind-unverified-cli-flag.sh

@@ -0,0 +1,309 @@
+#!/usr/bin/env bash
+# PreToolUse advisory — read the local CLI's own help before passing it a long
+# flag (Bash tool only).
+#
+# WHY: distilled from 399 recorded agent failures across 122 sessions (round
+# 059). "Flag guessed instead of read" accounts for ~20 of them, and the SAME
+# flag — `glab mr list --state` — failed in EIGHT independent sessions spread
+# over months. Every one of those eight was "fixed" the same way (read help, use
+# the supported flag) and every fix only repaired that one instance, so the class
+# came straight back. Same shape for `--jq` (3x), `--output`, `--pipeline-id`,
+# `--branch`, `--old-text`, `--allow-scripts`.
+#
+# The rule already existed in prose, but only at two NARROW firing points:
+# `worktree-isolation` (merge-authorization execution) and
+# `skill-extraction-workflow` (verifying CLI examples written INTO a reference).
+# Neither fires where the corpus actually fails: an agent about to run an
+# ordinary inspection command. This hook is that missing firing point.
+#
+# DELIBERATELY DOES NOT PARSE THE COMMAND. An earlier version segmented on shell
+# separators and handled heredocs, line continuations, the `--` terminator,
+# launcher words, global options and hierarchical subcommands. Independent review
+# found a new legal shell form it mishandled in essentially every round — fifteen
+# of them — because the set of legal shell spellings is open-ended and a regex
+# parser can only enumerate a prefix of it. This advisory does not need to know
+# where the subcommand is or when a heredoc ends. It needs to know that a risky
+# tool is being invoked with a long flag. So the predicate is: the tool name
+# appears as a WORD, and some long flag appears. Nothing else is inspected.
+#
+# PREDICATE CHOICE (unchanged, and why TOOLS is a list of TOOLS): flag
+# vocabularies are owned upstream and rot at every release, so the hook keys on
+# the small, slow-moving set of tool NAMES. The same reasoning retired the
+# parser: predicate on an invariant you own, never on someone else's vocabulary
+# or grammar.
+#
+# NON-BLOCKING by design; NOT a security boundary (obfuscated invocations are out
+# of scope, same declared class as the sibling hooks).
+#
+# ONE FIRE PER (session, tool): the first advisory for a tool in a session is
+# enough of a nudge; the agent can check the whole command line from there. And
+# within one Bash call only the FIRST listed tool is named — `glab ... && gh ...`
+# yields one advisory, about glab. The reminder says to check the flags in this
+# command, not just the named subcommand, so a second one would add nothing but
+# noise; naming every tool would also mean deciding where each invocation begins,
+# which is the parsing this hook exists without.
+#
+# ACCEPTED residuals — do NOT chase these with more string heuristics; chasing
+# them is precisely what produced the fifteen-round parser:
+#   - FALSE FIRE: a command that merely MENTIONS a listed tool alongside a long
+#     flag (a heredoc body, a commit message whose metacharacters defeat the
+#     quote mask, a grep pattern) draws one advisory for that session. One extra
+#     line of context; the text says to ignore it if the flag is already known.
+#   - FALSE FIRE: a help invocation that is not the command's first word
+#     (`cd /x && glab mr list --help`) still draws the advisory.
+#   - NON-FIRE: a payload hidden inside a whitespace-bearing quoted string
+#     (`sh -c 'glab mr list --state opened'`). The quote mask exists to stop
+#     commit messages and grep patterns from firing, and it cannot tell those
+#     from a launcher payload without parsing the command — which is the thing
+#     this hook does not do. Accepted in the QUIET direction: a missed nudge, not
+#     a wrong one.
+#   - DUPLICATE FIRE: two Bash calls using the same tool that start concurrently
+#     can both pass the marker check before either append lands, so both advise.
+#     The dedup is best-effort by construction and a lock is not worth buying for
+#     a duplicated one-line nudge.
+#   - NON-FIRE: short flags, and any tool outside TOOLS. Extend the list only
+#     when a tool accumulates recorded flag failures.
+#   - NON-FIRE: payloads over the 1 MiB read cap are ignored entirely.
+#
+# Degrade semantics (per hooks/AGENTS.md): jq missing → emit nothing (exit 0);
+# any internal issue → stay silent rather than disrupt the session.
+
+set -f
+
+# Bound the READ, not just the parse: this hook sits in front of every Bash call,
+# so its cost must not scale with command size. Past the cap jq sees truncated
+# JSON, yields nothing, and the hook exits silently.
+input=$(head -c 1048576)
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$cmd" ] && exit 0
+
+# Mask whitespace-bearing quoted spans so an ordinary commit message or grep
+# pattern mentioning a tool does not fire. Single-word quoted values keep their
+# content. This is the only text transform the hook performs.
+masked=$(printf '%s' "$cmd" | sed -E \
+  -e 's/"([^"[:space:];|&<>()]*)"/\1/g' \
+  -e "s/'([^'[:space:];|&<>()]*)'/\\1/g" \
+  -e 's/"[^"]*"/QUOTED/g' \
+  -e "s/'[^']*'/QUOTED/g")
+
+TOOLS='glab|gh|lark-cli|uv'
+
+# EVERY listed tool in the command, not just the first. Taking only the first
+# meant a tool that always trails another — `glab ... && gh ...` — could never
+# reach its own advisory once the leader was deduped, so it stayed silent for the
+# whole session. The dedup step below picks the first of these not yet advised.
+# Still no parsing: this is the set of tool words present, not their positions.
+tools_present=$(printf '%s' "$masked" | grep -Eow "(${TOOLS})" | awk '!seen[$0]++')
+[ -z "$tools_present" ] && exit 0
+tool=$(printf '%s' "$tools_present" | head -1)
+
+printf '%s' "$masked" | grep -Eq -- '(^|[[:space:]])--[a-zA-Z][a-zA-Z0-9-]+' || exit 0
+
+# Suppress only the unambiguous case: the command's FIRST WORD is the tool and it
+# is asking for help. Taking one token is not parsing the command; it keeps the
+# hook from telling someone to run the help they are already running, without a
+# whole-string help check. Suppression is additionally limited to commands with
+# NO shell separator: in `glab mr list --state opened && git --help` the first
+# word is still the tool, so a whole-command help grep swallowed the advisory for
+# a genuine invocation. Testing for a separator is one character class, not a
+# parse — a compound command simply never qualifies for suppression.
+first=$(printf '%s' "$masked" | awk '{print $1; exit}')
+# A NEWLINE separates commands just as `;` does, and grep is line-oriented so a
+# character class can never see one — a two-line command read as "simple" and its
+# second line's `--help` suppressed the advisory for the first line's invocation.
+# A standalone `--` hands the rest of the line to another program, so a `--help`
+# after it belongs to that program, not to this tool: `uv run --python 3.12 --
+# python --help` still needs the advisory for `--python`.
+sep_lines=$(printf '%s' "$masked" | grep -c '')
+if [ "$first" = "$tool" ] \
+   && [ "$sep_lines" -le 1 ] \
+   && ! printf '%s' "$masked" | grep -Eq -- '(^|[[:space:]])--([[:space:]]|$)' \
+   && ! printf '%s' "$masked" | grep -q '[;|&]'; then
+  # `-h` / `--help` anywhere in this simple command, or a bare `help` only in the
+  # SUBCOMMAND slot. Accepting a bare `help` anywhere matched positional
+  # arguments — `gh api help --paginate` asks for an endpoint named `help`, not
+  # for help — and swallowed the advisory for a genuine flag.
+  second=$(printf '%s' "$masked" | awk '{print $2; exit}')
+  { printf '%s' "$masked" | grep -Eq -- '(^|[[:space:]])(-h|--help)([[:space:]]|$)' \
+    || [ "$second" = "help" ]; } && exit 0
+fi
+
+# Best-effort per-session dedup. Any obstacle → skip dedup and remind again;
+# reminding twice is harmless, the failure modes below are not.
+#
+# HOSTILE-TMPDIR HARDENING (adversarial challenge; every attack below was
+# reproduced first-hand before being fixed). A predictable marker path directly
+# under TMPDIR let another user on a shared /tmp pre-create it as a SYMLINK (the
+# append wrote into an arbitrary file), as a FIFO (the append blocked until the
+# host killed the hook at its 10s timeout — a denial of service on the agent's
+# own Bash tool), or as a HARD LINK (which passes -f, -O and the symlink test
+# alike). Sanitizing the session id does not help; the path is guessable either
+# way. So the marker lives inside a directory this hook creates mode 0700 and
+# verifies it owns, where another user cannot plant anything.
+#
+# The append runs inside a subshell whose stderr is already redirected, which
+# closes the ENTIRE failed-open class — unwritable file, immutable flag, full
+# filesystem, a state change between the checks and the open. An explicit `-w`
+# check was removed once mutation showed it changed nothing the subshell did not
+# already cover; keeping it would also have hidden the subshell from every probe
+# by short-circuiting first. Enumerating open-failure causes is the same mistake
+# as enumerating shell forms.
+#
+# THREAT MODEL, stated so this stops being re-litigated one finding at a time.
+# The marker is a temp file holding a tool name. A successful attack on it buys
+# exactly one thing: getting this user's uid to append a fixed short string
+# (`glab`) to a file the attacker picks but cannot write themselves, or making
+# the advisory silent. It cannot execute anything, cannot read anything, and
+# carries no attacker-chosen content. The precondition walk below is therefore
+# sized to that payload: resolve the physical path once, refuse the whole
+# mechanism where the path is not exclusively ours or root's, and otherwise stop.
+# The ancestor check was rewritten three times as review found successive holes —
+# mode bits only, then bits plus sticky, then ownership, then physical
+# resolution — which is the same recurrence signal the parser produced. The
+# convergent form is the ownership invariant plus a physical path; further
+# hardening of a fixed-string append is not worth more rounds.
+#
+# UNVERIFIED PROPERTIES (labelled, not counted as audited). Both need a second
+# user id to construct, so no portable probe here reaches either, and a mutation
+# removing each one leaves the suite fully green:
+#   - the `-O` cross-uid rejection on the marker directory;
+#   - the third-party-ownership rejection in the ancestor walk (a directory owned
+#     by another non-root user, whose owner may rename its entries regardless of
+#     the mode bits).
+# The suite covers the same-uid and no-sticky directions of both. Do not read its
+# green as covering these; they rest on code inspection alone.
+# The suite does carry a PRESENCE check for each of them — a grep proving the
+# guard is still written — so deleting one silently turns the suite red even
+# though its behavior stays unverified. Presence is not behavior; the check
+# exists only so an unverified guard cannot also become an unnoticed one.
+session=$(printf '%s' "$input" | jq -r '.session_id // empty' 2>/dev/null)
+if [ -n "$session" ]; then
+  tmp_root="${TMPDIR:-/tmp}"
+  # PRECONDITION, because the TOCTOU below cannot be closed from bash. Every
+  # check on the marker directory is followed by a separate open of a path
+  # underneath it, and in a directory another user may write to they can rename
+  # the validated directory away and drop their own in its place between the two.
+  # Closing that needs a directory handle and openat-relative operations, which
+  # this language does not have. So the hook declines to dedup where dedup cannot
+  # be made safe, rather than pretending the window is shut: if the temp root is
+  # group- or world-writable and NOT sticky, skip the marker entirely and remind
+  # again. Sticky is what makes the usual shared /tmp safe — only the owner may
+  # rename or remove their entries there — and a per-user temp root is not
+  # other-writable at all, so this fires in neither normal case.
+  # Walk the whole ANCESTOR CHAIN, not just the temp root: a mode-0700 TMPDIR
+  # sitting under a world-writable non-sticky parent is swappable wholesale, so
+  # checking one level proves nothing about the path. Bounded by path depth, and
+  # `/` is never other-writable so it always terminates.
+  # Walk the PHYSICAL path. `dirname` on a logical path never resolves symlinks
+  # or `..`, so a relative TMPDIR or one whose target sits under a hostile
+  # ancestor walked a chain that does not exist on disk. Resolve once, up front.
+  # `cd -- ` because a TMPDIR of `-P` or `-L` is otherwise taken as a cd OPTION,
+  # leaving cd with no operand and landing in HOME — after which the ownership
+  # checks pass and the marker directory gets created there.
+  tmp_root=$(cd -- "$tmp_root" 2>/dev/null && pwd -P) || tmp_root=""
+  probe_dir="$tmp_root"
+  [ -z "$probe_dir" ] && probe_dir="/nonexistent"
+  walk_n=0
+  while : ; do
+    dir_perm=$(ls -ld "$probe_dir" 2>/dev/null | cut -c1-10)
+    if [ -z "$dir_perm" ]; then tmp_root=""; break; fi
+    # TWO independent ways an ancestor lets someone move the path out from under
+    # us, and the first is not about permission bits at all:
+    #   (1) it is OWNED by a third party — a directory owner may rename entries
+    #       in their own directory whatever the mode says, so 0755 owned by
+    #       another non-root user is just as exploitable as 0777;
+    #   (2) it is group/other-writable and NOT sticky — the classic shared-/tmp
+    #       hole, where any writer may rename anyone's entry.
+    # Earlier versions checked only the mode bits and then only bits-plus-sticky,
+    # and independent review walked in through the gap each time. Ownership is
+    # the invariant; the bits are the secondary case.
+    dir_owner=$(ls -ld "$probe_dir" 2>/dev/null | awk '{print $3}')
+    if [ ! -O "$probe_dir" ] && [ "$dir_owner" != "root" ]; then
+      tmp_root=""; break
+    fi
+    if { [ "$(printf '%s' "$dir_perm" | cut -c6)" = "w" ] \
+         || [ "$(printf '%s' "$dir_perm" | cut -c9)" = "w" ]; } \
+       && [ ! -k "$probe_dir" ]; then
+      tmp_root=""; break
+    fi
+    # Bound the walk: a legitimate path can have hundreds of components and each
+    # iteration spawns several processes, in front of every Bash call. Real temp
+    # roots are shallow; past the bound, refuse rather than keep paying.
+    walk_n=$((walk_n + 1))
+    if [ "$walk_n" -gt 40 ]; then tmp_root=""; break; fi
+    # `--` for the same reason `cd` needed it: a path component that looks like
+    # an option is taken as one. Not reachable from a `pwd -P` result today, but
+    # the guard costs nothing and the omission is the exact shape already found
+    # once in this file.
+    parent_dir=$(dirname -- "$probe_dir")
+    [ "$parent_dir" = "$probe_dir" ] && break
+    probe_dir="$parent_dir"
+  done
+  marker_dir="${tmp_root}/ccl-skills-cliflag"
+  # The explicit chmod is load-bearing: `mkdir -p -m 700` applies its mode only
+  # when it CREATES the directory, so an already-present group/world-writable one
+  # keeps its permissions and leaves the swap window open.
+  if [ -n "$tmp_root" ] \
+     && mkdir -p -m 700 "$marker_dir" 2>/dev/null \
+     && [ -d "$marker_dir" ] && [ ! -L "$marker_dir" ] && [ -O "$marker_dir" ] \
+     && chmod 700 "$marker_dir" 2>/dev/null; then
+    # Bound the NAME: an over-long session id became an over-long filename, and
+    # `>>file 2>/dev/null` applies redirections left to right, so the failed open
+    # printed before the suppression took effect.
+    safe_session=$(printf '%s' "$session" | tr -c 'A-Za-z0-9._-' '_' | cut -c1-100)
+    marker="${marker_dir}/${safe_session}"
+    marker_links=1
+    if [ -e "$marker" ]; then
+      marker_links=$(ls -ld "$marker" 2>/dev/null | awk '{print $2}')
+      case "$marker_links" in ''|*[!0-9]*) marker_links=99 ;; esac
+    fi
+    if [ -L "$marker" ] || [ "$marker_links" -gt 1 ] \
+       || { [ -e "$marker" ] && { [ ! -f "$marker" ] || [ ! -O "$marker" ]; }; }; then
+      : # unexpected object — skip dedup entirely, do not open it
+    else
+      # SIZE-capped, and the story of why is worth keeping. This cap was added,
+      # then removed on the argument that the line-count bound below already
+      # prevented the append — an argument checked only against a MANY-LINE file,
+      # where it happens to hold. A single enormous LINE has a line count of 1,
+      # sails past that bound, gets appended to, and is re-scanned by both greps
+      # on every matching call. Varying one dimension of the input and concluding
+      # over all of them is the exact mistake the round's own material names.
+      # Anything past a few lines of tool names is not ours: skip it, unread.
+      marker_bytes=$(wc -c "$marker" 2>/dev/null | awk '{print $1; exit}')
+      case "$marker_bytes" in ''|*[!0-9]*) marker_bytes=0 ;; esac
+      if [ "$marker_bytes" -gt 4096 ]; then
+        # Oversized: neither read nor written. Guarding only the read left the
+        # append running, which is how a single enormous line kept growing.
+        :
+      else
+          # Advise the first tool in this command not yet recorded this session; if
+        # every one of them is recorded, stay quiet.
+        if [ -f "$marker" ]; then
+          tool=""
+          for candidate in $tools_present; do
+            grep -Fqx "$candidate" "$marker" 2>/dev/null || { tool="$candidate"; break; }
+          done
+          [ -z "$tool" ] && exit 0
+        fi
+        # `grep -c ''` on an EMPTY file prints 0 but EXITS 1, so trusting the
+        # exit code produced "0\n0" and a stderr diagnostic from the test below.
+        marker_lines=$(grep -c '' "$marker" 2>/dev/null | head -1)
+        case "$marker_lines" in ''|*[!0-9]*) marker_lines=0 ;; esac
+        if [ "$marker_lines" -lt 32 ]; then
+          ( printf '%s\n' "$tool" >>"$marker" ) 2>/dev/null || true
+        fi
+      fi
+    fi
+  fi
+fi
+
+advisory="🔎 CLI flag 核验提醒（本会话对 \`${tool}\` 只提示一次）：\`${tool}\` 的 flag 词表**跨版本/跨平台差异很大**，凭记忆用 flag 是本仓记录中最高频的机械失败类之一——同一个 \`glab mr list --state\` 在 8 个独立会话里各踩一次，每次都只修了当次那一条。
+这条命令里的 flag 若**本会话还没在本机确认过**，先读一次对应子命令的 help 再用。
+已确认过就照常执行，忽略本提示。命令因无法识别的 flag 失败时，先怀疑这版不支持它，而不是先改用法之外的东西。"
+
+jq -nc --arg r "$advisory" \
+  '{hookSpecificOutput:{hookEventName:"PreToolUse",additionalContext:$r}}'
+exit 0