Skip to content

docs: add Windows hook wiring guide (fix silent hook failures) - #660

Merged
jeff-r2026 merged 1 commit into
Tencent:mainfrom
BeastAyyG:docs/windows-hook-wiring
Sep 20, 2026
Merged

jeff-r2026 merged 1 commit into
Tencent:mainfrom
BeastAyyG:docs/windows-hook-wiring

Conversation

@BeastAyyG

Copy link
Copy Markdown
Contributor

Summary

On Windows the hooks TeamAI injects are silently dead, so the team's shared
rules/skills and session stats never reach CodeBuddy / Qoder / WorkBuddy, and
even the "working" tools don't actually fire. This PR adds a bilingual guide
(docs/windows-hooks.md + docs/windows-hooks.zh-CN.md, matching the repo's
existing usage-guide / ci-code-erosion convention) explaining the cause and
a durable user-side fix, plus a concrete suggested upstream fix.

The problem

  1. Bare bash → WSL Node 18 crash. The injected hook command is
    bash -lc "teamai hook-dispatch ..." || true. On Windows bash resolves to
    the WSL launcher (C:\Windows\System32\bash.exe), whose bundled Node is v18
    and can't parse the TeamAI bundle. The crash is swallowed by || true, so
    teamai doctor still reports the hooks as "present" while they never run.
  2. hasShell() skips CodeBuddy / WorkBuddy. src/builtin-hooks.ts
    gates SHELL_DEPENDENT_TOOLS on fs.existsSync('/bin/sh'), which is always
    false on Windows. As a result those two agents get no hooks injected at
    all
    (WorkBuddy has a partial escape hatch via its bundled PortableGit
    sh.exe, but codebuddy is skipped unconditionally).

What this PR adds

A community guide covering:

  • The two failure modes and their root causes.
  • A durable user-side fix combining (A) the Git Bash absolute path in every
    agent settings file and (B) a WSL wrapper that delegates to native Windows
    teamai via cmd.exe so hooks survive a later teamai pull.
  • Verification (teamai doctor + per-tool hook-dispatch returning exit=0
    through both mechanisms).
  • Limitations and troubleshooting.

Suggested upstream fix (for maintainers)

Two small, backward-compatible changes would make Windows work out of the box —
described in detail in the doc:

  1. Make hasShell() Windows-aware (detect Git for Windows sh.exe/bash.exe
    or WSL bash instead of always returning false), so codebuddy /
    workbuddy hooks get injected.
  2. Default getDispatchCommand() to the Git Bash absolute path (or bundled
    PortableGit sh.exe) when process.platform === 'win32', avoiding the WSL
    Node 18 crash.

This PR is docs-only; I left the source untouched so maintainers can apply
the suggested fix in the way that best fits the codebase (and its existing
bundledShellFor / hasShellFor design).

Verification

Guide verified locally: teamai doctor ✔ for claude, codex, qoder, zcode,
codebuddy, workbuddy; every hook-dispatch returns exit=0 via both the Git
Bash path and the bare-bash-via-WSL mechanisms.

Document why TeamAI hooks silently fail on Windows (bare bash -> WSL Node 18 crash; hasShell() /bin/sh check skips codebuddy/workbuddy) and provide a durable user-side fix (Git Bash absolute path + WSL wrapper). Include a suggested upstream fix for maintainers. Bilingual (en + zh-CN) to match repo docs convention.
@jeff-r2026 jeff-r2026 self-assigned this Sep 19, 2026
@github-actions

Copy link
Copy Markdown
  • [P1 blocking] docs/windows-hooks.md:106 recommends creating CodeBuddy hooks with an absolute Git Bash command, but CodeBuddy launches hook commands through spawn('/bin/sh', ...). When /bin/sh is absent, execution fails before the configured command is reached. Likewise, merely making hasShell() detect Git Bash, as suggested at docs/windows-hooks.md:203, would inject still-unexecutable hooks. The guide’s central “all tools” workaround therefore does not fix CodeBuddy.

  • [P1 blocking] docs/windows-hooks.md:110 tells users to replace ZCode’s command field with Git Bash. On Windows, TeamAI intentionally emits a process entry using command: "wscript.exe" plus [vbsPath, dispatchCommand] arguments to preserve stdin and hide the console. Replacing only command leaves incompatible arguments and breaks ZCode’s existing Windows launcher. Remove ZCode from this generic procedure or document its complete schema correctly.

  • [P1 blocking] The PR description lacks the required end-to-end verification record. teamai doctor checks hook text presence, while manually running teamai hook-dispatch only tests the dispatcher; neither proves CodeBuddy, WorkBuddy, or another host actually launches the configured hook. This omission is particularly material because the proposed CodeBuddy wiring cannot pass the host’s /bin/sh launch step. Add an actual agent-triggered hook test plan and results before merge.

@jeff-r2026
jeff-r2026 merged commit 7301208 into Tencent:main Sep 20, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants