RTK compatibility: verify hook-ordering safety against branch-guard.sh before adoption

[Data-Wise]

Summary

Evaluating the third-party tool rtk-ai/rtk (a Claude Code hook that rewrites Bash commands for token savings) surfaced a potential compatibility risk with scripts/branch-guard.sh that hasn't been empirically verified yet.

The risk

RTK installs a PreToolUse hook on the same Bash matcher branch-guard.sh uses, and transparently rewrites commands before execution (e.g. git commit -m \"x\" → rtk git commit -m \"x\"). branch-guard.sh's catastrophic-command regexes are anchored to the start of the command:

(^|;|&&|\|\|)[[:space:]]*git[[:space:]]+(commit|push)
(^|;|&&|\|\|)[[:space:]]*git[[:space:]]+reset[[:space:]]+--hard

If RTK's hook runs first in the PreToolUse chain and inserts the rtk prefix before branch-guard evaluates the same event, the anchor no longer matches — branch-guard's protection could silently fail to trigger on main/protected branches.

This is currently unverified, not confirmed — neither Claude Code's multi-hook ordering semantics nor RTK's exact rewrite mechanism have been checked against real behavior.

Note to craft dev

Flagging this for anyone (human or agent) picking up craft dev work: do not install RTK globally on this machine or recommend it to others until the verification plan below has been run. The risk is specific to any tool that hooks PreToolUse/Bash and rewrites command text — RTK is the first such tool identified, but the same class of risk would apply to future tools with the same mechanism.

Verification plan

Full task-by-task plan (5 tasks, baseline → install → reproduce → diagnose → verdict + cleanup), using a disposable throwaway repo, not craft or any real project:

docs/specs/SPEC-rtk-branch-guard-hook-order-probe-2026-07-01.md

Related background: docs/internal/TUTORIAL-rtk-cli-token-proxy.md §4.2.

Acceptance criteria

• Verification plan executed per its own task list
• Verdict recorded (CONFIRMED BROKEN / CONFIRMED SAFE / INCONCLUSIVE) with evidence
• docs/internal/TUTORIAL-rtk-cli-token-proxy.md §4.2 updated to reflect the confirmed result instead of "unverified"
• Test machine's ~/.claude/settings.json restored to pre-probe state (RTK uninstalled) unless result is CONFIRMED SAFE and user explicitly opts to keep it

[Data-Wise]

Audit finding: this is an external-dependency risk assessment (RTK tool), not a craft code defect — needs an empirical multi-hook-ordering test run against the actual tool, which this session didn't have set up. Leaving open pending that verification.