Skip to main content

Hooks

Hooks are shell commands Knox runs at points in a turn. A cloned repo can ship them, so treat .knoxcoder/hooks.json like any other executable policy: review it, and do not open an untrusted folder as a trusted workspace.

Knox does not activate in an untrusted VS Code workspace (untrustedWorkspaces.supported: false). Repo-local hooks therefore never run on folder open. They are re-read on every call (tiny files), with that folder as cwd.

Files​

PathWhen
.knoxcoder/hooks.jsonEach workspace root
hooks: in .knoxcoder/config.yamlSame root
hooks: in ~/.knoxcoder/config.yamlUser-level; still runs once the workspace is trusted

Merge order: global yaml, then each root’s yaml and hooks.json (primary root first). Per-hook cwd is the root the file came from.

Type /hooks for active events and the last 30 audit-log lines. Knox: Test Hook (and the Hooks panel) runs one event against the current file. Knox: Show Hooks Log opens the log.

hooks.json​

{
"hooks": {
"PreToolUse": [
{
"matcher": "run_terminal_command|edit_file",
"command": "./check.sh",
"timeoutMs": 5000
}
]
}
}

matcher is a regex against the tool name, with and without the builtin_ prefix. Omit it or use * to match everything.

Events​

EventTypical use
SessionStartExtra context at the beginning of a session
UserPromptSubmitInspect or deny the user’s message
PreToolUseDeny or rewrite a tool call before it runs
PostToolUseExtra context from the result
StopAfter the turn ends

Hooks of one event run in file order. PreToolUse argument changes chain: each hook sees args as modified by the previous one.

Context from SessionStart and UserPromptSubmit is added to your message in a <hook_context> block.

Stdin JSON​

The command receives one JSON object on stdin:

{ "event": "PreToolUse", "cwd": "/path/to/folder", "toolName": "builtin_edit_file", "args": {}, "result": null, "prompt": null }

Fields present depend on the event (toolName / args / result / prompt).

Exit codes​

ExitEffect
0stdout JSON { decision, reason, updatedArgs, additionalContext }, or plain text treated as extra context
2Deny (PreToolUse, UserPromptSubmit only). stderr is the reason shown to you
Any other code, crash, or timeoutNever blocks. Logged to the console / audit log. Default timeout 10 s (timeoutMs overrides)

A broken hook must not freeze chat. If hooks “do nothing”, check the JSON is valid and read Knox: Show Hooks Log.

Team import​

Team bundles skip .knoxcoder/hooks.json unless you choose Allow hooks. Hooks run commands from the repo.

Next​

AGENTS.md and rules · Team bundles · Troubleshooting