docs(windows): Sequant's bash hooks block every tool call on native Windows without Git Bash since Claude Code 2.1.299 — document it and make doctor fail

Aperta
  • Qualcosa non va?
#1,572 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
73/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
bash, typescript
Ambito
cli, devtools, documentation

Direzione di ricerca

Read the Platform Support table in README.md, the Windows section in docs/troubleshooting.md, and the Platform check in src/commands/doctor.ts with its tests in src/commands/doctor.test.ts. Check how doctor detects native Windows and whether bash is on PATH, then update the docs and cover both detection branches in tests. Done when the docs explain the impact and recovery steps, and doctor fails without bash but keeps its warning when bash is available.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

bug documentation upstream

Source: upstream triage of Claude Code v2.1.299, 2026-10-20 (replaces the auto-filed stub #1538)

Problem

Claude Code v2.1.299: "Windows: Fixed PreToolUse and PermissionRequest hooks that set no shell failing open when Git for Windows isn't installed; a guard that fails now blocks the call".

Sequant's hooks are bash scripts registered with no shell and matcher "*", in both places it ships them:

  • plugin/hooks/hooks.json:3-10 (plugin installs)
  • templates/settings.json:3-10 (projects set up with sequant init)

On native Windows, Git for Windows is optional: Claude Code's setup docs say that without it, Claude Code runs shell commands with the PowerShell tool. So for a native-Windows user without Git Bash:

  • before 2.1.299: pre-tool.sh never ran, so every Sequant guardrail was silently off;
  • from 2.1.299: the hook fails, so every tool call is blocked. CLAUDE_HOOKS_DISABLED cannot help because the script never starts.

What users are told today: README Platform Support says "Windows Native ⚠️ CLI only" (README.md:344), and docs/troubleshooting.md:625 ("bash: command not found") recommends WSL. Neither says that installing the plugin or running sequant init on native Windows without Git Bash blocks every tool call in Claude Code. sequant doctor warns "Running on native Windows - WSL recommended for full functionality (hooks, scripts)" (src/commands/doctor.ts:1121-1127) whether or not bash is available.

Phase agents still run the SDK-bundled Claude Code 2.1.296, where the failing hook fails open (#1571).

Acceptance Criteria

  • AC-1: The README Platform Support table and the troubleshooting Windows section state that Sequant's hooks need bash (WSL or Git for Windows), that without it Claude Code ≥ 2.1.299 blocks every tool call once the plugin is installed or sequant init has run, and how to recover (install Git for Windows or use WSL; or uninstall the plugin / remove the hook entries). Evidence: the diff of README.md and docs/troubleshooting.md.
  • AC-2: On native Windows with no bash on PATH, sequant doctor reports a fail (not warn) Platform check whose message says hooks will block every tool call and names the fix; with bash available it keeps today's warning. Evidence: unit tests for both branches in src/commands/doctor.test.ts with the platform and bash lookup mocked.

May touch

README.md, docs/troubleshooting.md, src/commands/doctor.ts (+ a small bash-on-PATH helper if none exists), src/commands/doctor.test.ts, CHANGELOG.md.

Non-Goals

  • Changing plugin/hooks/hooks.json or the hook scripts (for example a PowerShell shell fallback). Hook content is under the plugin freeze; revisit when it lifts.
  • Supporting native Windows without bash.
Lingua principale
TypeScript
Stelle
1
Fork
1
Merge medio
11h 3m
PR unite (30g)
84

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di sequant-io/sequant

Tutte le issue di sequant-io/sequant

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.