dotharness/dotcraft/create-hooks

Create DotCraft Hooks

Overview

DotCraft hooks are lifecycle event triggers that run external shell commands at key agent execution points. Hooks are configured in hooks.json and can observe, log, or block agent actions.

Workflow

1. Establish the goal (security guard, auto-format, logging, notification, etc.), asking only if the request leaves it ambiguous
2. Determine which lifecycle event(s) to use
3. Determine scope: workspace (.craft/hooks.json), global (~/.craft/hooks.json), or plugin (<plugin-root>/hooks/hooks.json)
4. Generate the hooks.json config and any helper scripts
5. Place scripts in .craft/hooks/, the user's chosen global hooks directory, or the plugin's hooks/ directory

Config File Locations

Global hooks load first, workspace hooks are appended, and enabled plugin hooks run after config hooks. Plugin hooks are additive and read-only from Desktop; Desktop manages only user state.

Config Format

{
    "hooks": {
        "<EventName>": [
            {
                "matcher": "<regex for tool names>",
                "hooks": [
                    {
                        "type": "command",
                        "command": "<shell command>",
                        "timeout": 30
                    }
                ]
            }
        ]
    }
}

Fields

Trust and User State

DotCraft stores per-hook user state in global ~/.craft/config.json under Hooks.State.

{
  "Hooks": {
    "State": {
      "<hook-key>": {
        "Enabled": false,
        "TrustedHash": "sha256:..."
      }
    }
  }
}

• Enabled: false disables one hook without editing hooks.json.
• TrustedHash records the normalized hook definition the user approved.
• Config and plugin hooks must be trusted before they run. Modified hooks need trust again.
• Do not write trust state into workspace .craft/config.json; it is personal user state.

For plugin hooks, commands may use ${DOTCRAFT_PLUGIN_ROOT} and ${DOTCRAFT_PLUGIN_DATA}. DotCraft expands these variables in the command and also injects them as environment variables.

Lifecycle Events

DotCraft emits both camelCase and snake_case field names. Prefer snake_case in portable scripts.

Exit Codes

JSON Output

Hooks may print plain text or JSON. Plain text becomes additional context for context-capable events. JSON output can use:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Model-visible guidance"
  },
  "decision": "block",
  "reason": "Why the action should stop or continue with feedback",
  "systemMessage": "Optional user-visible status"
}

Use hookSpecificOutput.additionalContext for guidance that should be shown to the model without leaking raw JSON.

Built-in Tool Names (for matcher)

Matcher is case-insensitive regex. Examples: "" (all), "WriteFile|EditFile" (write ops), ".*File" (all file ops), "Exec" (shell only).

The optional if field supports portable conditions such as Bash(git commit:*). DotCraft maps common tool aliases: shell execution to Bash, full-file writes to Write, and search/replace edits to Edit.

Platform Differences

• Linux/macOS: Commands run via /bin/bash -c '<command>'. Use standard bash syntax, jq for JSON parsing.
• Windows: PowerShell commands run via pwsh when installed, otherwise Windows PowerShell, with -File <temp.ps1>. Use PowerShell syntax and ConvertFrom-Json for JSON parsing. If neither is available, the default is cmd; set shell to powershell or pwsh when the hook requires PowerShell.

Windows (PowerShell) stdin reading pattern

$input_data = [Console]::In.ReadToEnd() | ConvertFrom-Json
$toolName = $input_data.toolName
$toolArgs = $input_data.toolArgs

Windows blocking pattern (exit 2)

$input_data = [Console]::In.ReadToEnd() | ConvertFrom-Json
# ... check logic ...
if ($shouldBlock) {
    [Console]::Error.WriteLine("Block reason here")
    exit 2
}
exit 0

Linux/macOS stdin reading pattern

INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.toolName // empty')
TOOL_ARGS=$(echo "$INPUT" | jq -c '.toolArgs')

Best Practices

1. Always consume stdin — even if unused, read it (cat > /dev/null or [Console]::In.ReadToEnd() | Out-Null) to avoid broken pipe errors
2. Use `jq` (bash) or `ConvertFrom-Json` (PowerShell) for JSON parsing
3. Append `|| true` (bash) or `try/catch` (PowerShell) inside helper scripts for non-critical work
4. Set reasonable timeouts — default is 30s, increase for slow operations
5. Use `exit 2` intentionally — reserve it for blocking events or for asyncRewake feedback
6. Write block reasons to stderr — echo "reason" >&2 (bash) or [Console]::Error.WriteLine("reason") (PowerShell)
7. No interactive commands — hooks run in background without user input
8. Place complex logic in script files — store in .craft/hooks/ and reference from hooks.json

Generation Rules

When generating hooks for the user:

1. Read the shell from workspace context — use its syntax, or explicitly set shell when the hook requires PowerShell; use bash on Linux/macOS
2. For complex hooks, create script files in the selected hooks directory and reference them in the command field
3. Merge with existing config — if .craft/hooks.json already exists, read it first and merge new hooks into the existing config rather than overwriting
4. Validate event names — use an event name from the Lifecycle Events table above
5. Ensure hooks are enabled — check that config.json does not have "Hooks": { "Enabled": false }
6. Leave trust to the user — mention that new or modified hooks must be trusted through Desktop Hooks settings or hooks/setState