Native ZCode Agent does not trigger hooks configured in ~/.zcode/cli/config.json

[laozhouxingke]

Problem

When using ZCode Agent (the native built-in agent), lifecycle hooks configured under hooks.events in ~/.zcode/cli/config.json are never triggered.

Config used

{
  "hooks": {
    "enabled": true,
    "timeoutMs": 60000,
    "maxOutputBytes": 32768,
    "events": {
      "UserPromptSubmit": [
        {
          "matcher": "",
          "hooks": [
            {
              "type": "command",
              "command": "node",
              "args": ["/path/to/hook.js"]
            }
          ]
        }
      ]
    }
  }
}

The hook script writes to a debug log on entry (before any stdin read), so if it were invoked at all, the log would appear. After multiple ZCode Agent sessions with prompts and tool use, the log file is never written.

What was also tried

• Registering hooks via the plugin system (~/.zcode/cli/plugins/) — same result, hooks not triggered for ZCode Agent sessions
• Hook command executes correctly when invoked manually via PowerShell

Expected behavior

Hooks in hooks.events should fire for ZCode Agent sessions (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, etc.) the same way they work for external CLI subagents.

Question

Is this a known limitation? Is there a supported way to receive lifecycle events from ZCode Agent sessions externally (e.g., a local HTTP/WebSocket API, IPC, or log file)?

[github-actions]

👋 感谢你的反馈，我们已经收到。

• 维护者会在 3 个工作日内 给出首次响应。
• 状态保持为 status: 待评估，你可以随时补充信息。
• 信息不全时我们会打上 needs: 更多信息 标签并 @ 你。

---

👋 Thanks — we've received your issue.

• A maintainer will respond within 3 business days.
• Status stays at status: 待评估 (Triage); feel free to add context.
• If we need more details, we'll add needs: 更多信息 and ping you.

[Krutov-mcp]

Adding to the original report — I ran into the same core issue (hooks not firing), but was able to get them working after changing the format. Leaving notes in case useful.

Diagnosis

When using exec form with a separate args field (as described in Claude Code docs and Discussion #9), ZCode marks the entire config.json as invalid and no hooks are registered at all:

event: config.file.invalid
diagnosticMessage: "hooks.events.UserPromptSubmit.0.hooks.0: Unrecognized key: \"args\""
diagnosticCode: config_file_invalid

Found in ZCode logs at ~/.zcode/cli/log/zcode-YYYY-MM-DD.jsonl.

The args field appears to no longer be recognized by the validator (schema?). Notable behavior: a single invalid entry disables the entire hooks section, including any other valid hooks.

Workaround — shell form only

Using a single command string with quoted paths (instead of args) makes everything work end-to-end:

{
  "hooks": {
    "enabled": true,
    "events": {
      "UserPromptSubmit": [{
        "hooks": [{
          "type": "command",
          "command": "\"C:\\Program Files\\nodejs\\node.exe\" \"C:\\Users\\<user>\\.zcode\\hooks\\my-hook.js\"",
          "timeoutMs": 5000
        }]
      }]
    }
  }
}

The node script reads JSON from stdin and returns {hookSpecificOutput: {hookEventName, additionalContext}} — additionalContext is injected into the model context as documented.

Events verified working (empirically, 2026-07-20)

Desktop build on Windows 10:

• ✅ SessionStart
• ✅ UserPromptSubmit — additionalContext injection confirmed
• ✅ Stop — fires only after the model fully completes its response (not on user interruption)
• ✅ PreToolUse with matcher: "Bash" — permissionDecision: "deny" blocks the tool call

Possible doc discrepancy

Discussion #9 by @GoooIce mentions args as part of the schema (based on decompile analysis, Jun 14 2026). On my current build (Jul 20 2026), args is rejected with config.file.invalid. Either (a) args was removed/restricted in a build between those dates, or (b) the desktop client validator is stricter than the embedded runtime. Would be useful to know which format is intended canonical.

Working 3-hook setup (for reference)

Deployed three production hooks (node.exe + JS script, shell form as above):

1. UserPromptSubmit → workflow-trigger reminder (L-Z069-like pattern)
2. Stop → verify-before-complete checklist (block if "done" without test markers)
3. PreToolUse(Bash) → block destructive commands (rm -rf, git push -f, curl|sh)

All three work end-to-end after switching to shell form. Hook logs are written, additionalContext shows up in model context, permissionDecision: "deny" properly blocks tool calls.

Hope this helps clarify what works and what doesn't right now.