when

Optional. A shell Precondition that runs before the main shell decision. An ordinary non-zero exit skips the entire Hook—no shell, no owned Action, no Hook Result, no Action Effect, and no Evaluation Report row:

{
  "local": {
    "guard-package-managed": {
      "description": "Only guard repos that have a package manifest",
      "event": "tool_call",
      "when": "test -f package.json",
      "shell": "false"
    }
  }
}

• Type string · optional · every Hook
• Runs through the real local shell like shell does; exact "true" and "false" also run as optimized shortcuts.
• Ordinary non-zero skips the Hook as if it had not matched. Only an infrastructure failure produces the Event-specific code-null result.
• Evaluation order is filter → when → shell, so Filter matching occurs before either shell command runs.