zai-org / zai-org/zcode-plugins

video-agent-kit (0.4.3): hooks invoke python3, which doesn't exist on Windows — SessionStart/UserPromptSubmit/Stop hooks fail on every trigger

Open Beginner friendly
#14 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
39
Forks
20
PR merge metrics
No merged PRs in 30d

Description

Environment

  • OS: Windows 11 (build 10.0.26200)
  • ZCode: desktop client
  • Plugin: video-agent-kit 0.4.3
  • Python: 3.14 (python.org install — exposes python.exe and the py launcher; there is no python3 on PATH)

Symptom

Every SessionStart, UserPromptSubmit, and Stop event logs a hook failure (hook.run.failed in the ZCode log, source plugin.video-agent-kit@zcode-plugins-official.*, ~50 ms duration = command-not-found). Across one day of normal use this produced ~75 failure entries across all open sessions.

Root cause

hooks/hooks.json invokes all three hook scripts through python3:

  • env_check.py (SessionStart)
  • check_video_input.py (UserPromptSubmit)
  • check_closeout.py (Stop)

Windows Python installers do not create a python3 executable, so the command never resolves.

Suggested fix

Any of:

  1. Invoke the scripts with python (present on Windows and nearly all dev machines), or
  2. Resolve the interpreter dynamically at hook time (prefer python3, fall back to python/py), or
  3. Document a python3-on-PATH requirement for Windows users.

Side note: env_doctor.py correctly pins the MCP SDK to >=1.0.0,<2.0.0 — installing MCP SDK 2.x satisfies import mcp but breaks the 1.x Server API the plugin uses, so that version-pinned check is doing real work.

Local workaround (for anyone hitting this)

Patch the three interpreter refs in the plugin's hooks/hooks.json from python3 to python, and/or drop a python3.cmd shim (@python %*) into a PATH directory that Windows processes can see (e.g. the Python install dir). Both verified working on 0.4.3.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with hooks/hooks.json and inspect the commands for env_check.py, check_video_input.py, and check_closeout.py. Reproduce the hook invocations on Windows with the available Python launchers, then verify that SessionStart, UserPromptSubmit, and Stop no longer produce command-not-found failures.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
tooling
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
85/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.