Hooks - Qoder

Hooks let you run custom logic at key points during Agent execution in QoderWork — no source code changes required. Edit a JSON config file to:

Block dangerous operations before a tool runs
Auto-lint after every file write to enforce code style
Send a desktop notification when the Agent finishes, so you don’t have to watch the screen

Unlike prompt instructions, hooks are deterministic — when the event fires, your script runs. No model interpretation, no drift.

Quick Start

Here is an example that blocks rm -rf commands:

Create the script

mkdir -p ~/.qoderwork/hooks
cat > ~/.qoderwork/hooks/block-rm.sh << 'EOF'
#!/bin/bash
input=$(cat)
command=$(echo "$input" | jq -r '.tool_input.command')

if echo "$command" | grep -q 'rm -rf'; then
  echo "Dangerous command blocked: $command" >&2
  exit 2
fi

exit 0
EOF
chmod +x ~/.qoderwork/hooks/block-rm.sh

Add the config

Add the following to ~/.qoderwork/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.qoderwork/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

Verify it works

Open QoderWork and ask the Agent to run a command containing rm -rf. The hook blocks execution and feeds the error message back to the Agent.

How It Works

The hook lifecycle comes down to three steps: write a script, register it in config, and it takes effect automatically. When the Agent reaches a lifecycle event (such as “before a tool call”), QoderWork checks whether any hooks are registered for it:

QoderWork loads all hook configurations at startup.
During Agent execution, QoderWork encounters a lifecycle event (e.g. PreToolUse).
QoderWork iterates through every hook group registered for that event and evaluates the matcher against the current context.
Hooks with a matching matcher run their shell scripts in order.
Each script receives event context as JSON via stdin and returns a decision through its exit code and stdout.
QoderWork reads the result and decides what to do next — proceed or block.

Prerequisites

jq: The example scripts use jq to parse JSON. Install it with brew install jq on macOS or apt install jq on Linux.
Script permissions: Every hook script must be executable (chmod +x).

Creating Hooks

1. Decide What You Need: Pick an Event and a Matcher

Start by deciding where to intervene and what to match:

I want to intercept/handle [what operation] at [what point]?
   ↓                                          ↓
 write a matcher                         pick an event

Requirement	Event	Matcher
Check before the Agent runs any shell command	PreToolUse	`"Bash"`
Process after the Agent writes or edits a file	PostToolUse	`"Write \| Edit"`
Log when any tool call fails	PostToolUseFailure	`"Bash"` or omit
Screen every user prompt	UserPromptSubmit	Omit (matches all)
Show desktop notifications (completion, permission, etc.)	Notification	Omit (matches all) or match by notification type
Intercept only MCP tools	PreToolUse	`"mcp__.*"`

2. Write the Hook Script

A hook script is a standard shell script that follows this protocol: Input: JSON event context delivered via stdin. Output: Determined by the exit code.

exit 0   →  Allow (continue execution)
exit 2   →  Block (stop the action; stderr is injected into the conversation)
other    →  Error (continue execution; stderr is shown to the user)

Script template:

#!/bin/bash

# 1. Read the JSON input from stdin
input=$(cat)

# 2. Extract the fields you care about with jq
tool_name=$(echo "$input" | jq -r '.tool_name')
tool_input=$(echo "$input" | jq -r '.tool_input')

# 3. Write your logic
if [ "$tool_name" = "Bash" ]; then
  command=$(echo "$input" | jq -r '.tool_input.command')

  if echo "$command" | grep -qE 'rm\s+-rf|DROP\s+TABLE'; then
    echo "Operation denied: $command" >&2
    exit 2
  fi
fi

# 4. Allow
exit 0

You can also output JSON on stdout when exiting with exit 0 for finer-grained control:

#!/bin/bash
input=$(cat)

echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"This operation is not allowed"}}'
exit 0

3. Register the Script in Your Config

Add the script path under the corresponding event in ~/.qoderwork/settings.json:

{
  "hooks": {
    "EventName": [
      {
        "matcher": "match condition (optional)",
        "hooks": [
          {
            "type": "command",
            "command": "path/to/script"
          }
        ]
      }
    ]
  }
}

4. Test and Debug

You can test your scripts directly from the terminal by piping JSON input:

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"},"hook_event_name":"PreToolUse"}' \
  | ~/.qoderwork/hooks/block-rm.sh
echo "Exit code: $?"

Check the stderr output (the block message):

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' \
  | ~/.qoderwork/hooks/block-rm.sh 2>&1

Configuring Hooks

Config File Location

QoderWork loads hook configurations from the user-level settings file:

Location	Scope	Description
`~/.qoderwork/settings.json`	User (global)	Personal config, applies to all QoderWork sessions

Hot reload is not yet supported — restart QoderWork after editing hook configurations for changes to take effect.

Config Format

{
  "hooks": {
    "EventName": [
      {
        "matcher": "match condition",
        "hooks": [
          {
            "type": "command",
            "command": "command to execute"
          }
        ]
      }
    ]
  }
}

Field	Required	Description
`type`	Yes	Must be `"command"`
`command`	Yes	Shell command or path to the script to run
`timeout`	No	Timeout in seconds (defaults to 30). Custom values are not yet supported; configurable timeouts are coming in a future release
`matcher`	No	Match condition. If omitted, the hook fires on every occurrence of that event

You can define multiple matcher groups under a single event, and each group can contain multiple hook commands.

Matcher Rules

matcher determines when a hook fires. What it matches against depends on the event (see each event’s description).

Pattern	Meaning	Example
Omit or `"*"`	Match everything	All tools trigger the hook
Exact value	Exact match	`"Bash"` fires only for the Bash tool
`\|`-separated	Match multiple values	`"Write \| Edit"` fires for Write or Edit
Regex	Regex match	`"mcp__.*"` matches all MCP tools

Tool Name Mapping

QoderWork supports two sets of tool names — native names and compatible names. You can use either in your matchers; QoderWork maps them internally.

QoderWork native name	Compatible name	Description
`run_in_terminal`	`Bash`	Execute shell commands
`read_file`	`Read`	Read file contents
`create_file`	`Write`	Create / write a file
`search_replace`	`Edit`	Edit a file
`delete_file`	-	Delete a file
`grep_code`	`Grep`	Search file contents
`search_file`	`Glob`	Match files by name
`list_dir`	`LS`	List a directory
`task`	`Task`	Launch a subtask / sub-agent
`Skill`	-	Invoke a skill
`search_web`	`WebSearch`	Web search
`fetch_content`	`WebFetch`	Fetch web page content
`todo_write`	`TodoWrite`	Write a TODO
`ask_user_question`	-	Ask the user a question
`search_memory`	-	Search memory
`update_memory`	-	Update memory
`mcp__<server>__<tool>`	same	MCP tools

Writing Hook Scripts

Hook scripts receive JSON input via stdin and communicate results through their exit code and stdout. This section covers the input/output format common to all events. For event-specific fields, see Hook Events.

QoderWork currently does not inject environment variables into hook scripts. All data is passed via stdin JSON. If you need session ID, working directory, or tool information, parse them from the stdin JSON input.

Input

Your hook script receives JSON data via stdin. Every event includes these common fields:

Field	Description
`session_id`	Current session ID
`transcript_path`	Path to the session transcript JSONL file (e.g. `~/.qoderwork/projects/<encoded-path>/<session-id>.jsonl`)
`cwd`	Current working directory
`hook_event_name`	Name of the event that triggered this hook

Each event adds its own fields on top of these (see the individual event descriptions). Parse the input with jq:

#!/bin/bash
input=$(cat)
tool_name=$(echo "$input" | jq -r '.tool_name')

Output

Hooks communicate results through exit code and stdout. exit 0 indicates success. QoderWork parses stdout — some events (like UserPromptSubmit, SessionStart) support plain text context injection or JSON fine-grained control. See each event’s description for details. exit 2 indicates a blocking error (only effective for blockable events). stdout is ignored; stderr is fed back to the Agent as an error message. The specific effect depends on the event: PreToolUse blocks tool execution, UserPromptSubmit rejects the prompt, Stop prevents the Agent from stopping, etc. Other exit codes are treated as non-blocking errors — they don’t affect the execution flow, and stderr is only recorded in logs.

Hook Events

UserPromptSubmit

Fires after the user submits a prompt, before the Agent begins processing it. Use it for prompt screening, content filtering, or auto-injecting context. Matcher: None. This event fires for all user input. Extra input fields:

{
  "session_id": "abc-123",
  "cwd": "/Users/you",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "Organize my Downloads folder by file type"
}

Blocking the prompt: Exit with code 2. The stderr content is displayed to the user as an error, and the Agent does not process the prompt. stdout JSON fields (when exit code is 0):

Field	Type	Description
`hookSpecificOutput.hookEventName`	string	Fixed to `"UserPromptSubmit"`
`hookSpecificOutput.additionalContext`	string	Additional context injected into the Agent’s conversation

PreToolUse

Fires before a tool executes. Can block tool execution. Ideal for blocking dangerous commands, validating file paths, or enforcing permissions. Matcher: Tool name (e.g. Bash, Write, Edit, Read, or MCP tool names like mcp__server__tool). Extra input fields:

{
  "session_id": "abc-123",
  "cwd": "/Users/you",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "rm -rf /tmp/build" }
}

Blocking tool execution: Exit with code 2. The stderr content is returned to the Agent as an error. stdout JSON fields (when exit code is 0):

Field	Type	Description
`hookSpecificOutput.hookEventName`	string	Fixed to `"PreToolUse"`
`hookSpecificOutput.permissionDecision`	string	`"allow"`, `"deny"`, or `"ask"`
`hookSpecificOutput.permissionDecisionReason`	string	Reason for the decision
`hookSpecificOutput.updatedInput`	object	Modified tool input parameters (optional)
`hookSpecificOutput.additionalContext`	string	Additional context (optional)

PostToolUse

Fires after a tool executes successfully. Not blockable. Use it for auto-linting, logging, or result analysis. Matcher: Tool name. Extra input fields:

{
  "session_id": "abc-123",
  "cwd": "/Users/you",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": { "file_path": "/path/to/file.ts", "content": "..." },
  "tool_response": "File written successfully"
}

stdout JSON fields (when exit code is 0):

Field	Type	Description
`hookSpecificOutput.hookEventName`	string	Fixed to `"PostToolUse"`
`hookSpecificOutput.feedback`	string	Feedback displayed to the user

PostToolUseFailure

Fires when a tool call fails. Not blockable. Use it for error monitoring, retry suggestions, or logging. Matcher: Tool name. Extra input fields:

{
  "session_id": "abc-123",
  "cwd": "/Users/you",
  "hook_event_name": "PostToolUseFailure",
  "tool_name": "Bash",
  "tool_input": { "command": "npm test" },
  "error": "Command exited with non-zero status code 1"
}

Field	Type	Description
`error`	string	The error message from the failed tool execution

Stop

Fires after the Agent completes its response. Can block the Agent from stopping. Use it for quality gates, desktop notifications, or logging. Matcher: None. This event fires whenever the Agent stops. Extra input fields:

{
  "session_id": "abc-123",
  "cwd": "/Users/you",
  "hook_event_name": "Stop",
  "stop_hook_active": false
}

Field	Type	Description
`stop_hook_active`	boolean	`true` when the Agent is retrying after a previous Stop hook block. Your script must check this field and exit 0 when it is true to prevent infinite loops.

Blocking the Agent from stopping: Exit with code 2. The block reason is injected into the conversation as a user message, and the Agent continues working. stdout JSON fields (when exit code is 0):

{
  "decision": "block",
  "reason": "Tests failing. Fix them before completing."
}

Field	Type	Description
`decision`	string	`"block"` (prevent the Agent from stopping and make it continue working)
`reason`	string	Reason for blocking; injected into the conversation as a message

Preventing infinite loops: When a Stop hook blocks the Agent (exit 2), the Agent retries and the Stop event fires again with stop_hook_active: true. Your script must check this field and exit 0 when it is true, otherwise the hook will block indefinitely.

SessionStart

Fires when a session starts. Matcher: Session source

Matcher value	Trigger scenario
`startup`	New session starts
`resume`	Resuming an existing session
`compact`	After context compaction completes

Extra input fields:

{
  "source": "startup",
  "agent_type": "coder",
  "model": ""
}

SessionEnd

Fires when a session ends. Matcher: End reason

Matcher value	Trigger scenario
`prompt_input_exit`	User exits input (Ctrl+D, etc.)
`other`	Other reasons

Extra input fields:

{
  "reason": "prompt_input_exit"
}

SubagentStart / SubagentStop

Fires when a subagent starts or completes. SubagentStop, like Stop, can block the subagent from stopping. Matcher: Agent type name SubagentStart extra input fields:

{
  "agent_id": "83f488ef",
  "agent_type": "general-purpose"
}

SubagentStop extra input fields:

{
  "agent_id": "83f488ef",
  "agent_type": "general-purpose",
  "agent_transcript_path": "",
  "stop_hook_active": false
}

Field	Type	Description
`agent_id`	string	Subagent ID
`agent_type`	string	Subagent type (e.g. `"general-purpose"`)
`agent_transcript_path`	string	Path to the subagent’s transcript file (SubagentStop only)
`stop_hook_active`	boolean	Whether this is a retry after a previous SubagentStop block (SubagentStop only)

PreCompact

Fires before context compaction. Matcher: Trigger method

Matcher value	Trigger scenario
`manual`	User manually runs /compact
`auto`	Auto-triggered when context window is full

Extra input fields:

{
  "trigger": "manual",
  "custom_instructions": "Preserve all tool call results"
}

Notification

Fires on notification events (permission requests, task completion, etc.). Matcher: Notification type

Matcher value	Trigger scenario
`permission`	Permission request notification
`result`	Agent result notification

Extra input fields:

{
  "message": "Agent is requesting permission to run: rm -rf node_modules",
  "title": "Permission Required",
  "notification_type": "permission"
}

PermissionRequest

Fires when a tool execution requires user authorization. Matcher: Tool name Extra input fields:

{
  "tool_name": "Bash",
  "tool_input": {"command": "rm -rf node_modules"}
}

Scenario Examples

Block Dangerous Commands

Script ~/.qoderwork/hooks/block-dangerous.sh:

#!/bin/bash
input=$(cat)
command=$(echo "$input" | jq -r '.tool_input.command')

if echo "$command" | grep -qE 'rm\s+-rf|DROP\s+TABLE|mkfs|dd\s+if='; then
  echo "Dangerous command blocked: $command" >&2
  exit 2
fi

exit 0

Config: event PreToolUse, matcher Bash, command ~/.qoderwork/hooks/block-dangerous.sh.

Keep Agent Working

Check for unfinished tasks when the Agent stops. If there are uncommitted git changes, block the Agent from stopping. Script ~/.qoderwork/hooks/check-continue.sh:

#!/bin/bash
# Check for uncommitted git changes
if [ -n "$(git status --porcelain 2>/dev/null)" ]; then
  echo "Uncommitted changes detected, please complete git commit" >&2
  exit 2
fi

exit 0

Config: event Stop, command ~/.qoderwork/hooks/check-continue.sh.

Inject Context on Prompt Submit

Automatically inject the current git branch info as Agent context before each user prompt. Script ~/.qoderwork/hooks/inject-branch.sh:

#!/bin/bash
branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
if [ -n "$branch" ]; then
  echo "Current git branch: $branch"
fi
exit 0

Config: event UserPromptSubmit, command ~/.qoderwork/hooks/inject-branch.sh.

Desktop Notification on Events

When the Agent finishes a task or needs authorization, show a desktop notification. Prefer the Notification event (not Stop): QoderWork delivers message, title, and notification_type in the stdin JSON for each notification. Script ~/.qoderwork/hooks/notify.sh (macOS):

#!/bin/bash
input=$(cat)
message=$(echo "$input" | jq -r '.message // empty')
title=$(echo "$input" | jq -r '.title // "QoderWork Agent"')
notification_type=$(echo "$input" | jq -r '.notification_type // empty')

if [ -z "$message" ]; then
  exit 0
fi

# notification_type is present in stdin (e.g. "permission", "result"); branch on it for different UX if needed
osascript -e "display notification \"$message\" with title \"$title\""

exit 0

Config: event Notification, no matcher, command ~/.qoderwork/hooks/notify.sh.

Prompt Content Screening

Script ~/.qoderwork/hooks/check-prompt.sh:

#!/bin/bash
input=$(cat)
prompt=$(echo "$input" | jq -r '.prompt')

if echo "$prompt" | grep -qiE '(password|secret|api_key|token)\s*[:=]\s*\S+'; then
  echo "Detected possible sensitive data in your prompt. Please review and resubmit." >&2
  exit 2
fi

exit 0

Config: event UserPromptSubmit, no matcher, command ~/.qoderwork/hooks/check-prompt.sh.

Log Tool Failures

Script ~/.qoderwork/hooks/log-failure.sh:

#!/bin/bash
input=$(cat)
tool_name=$(echo "$input" | jq -r '.tool_name')
error=$(echo "$input" | jq -r '.error')
timestamp=$(date '+%Y-%m-%d %H:%M:%S')

echo "[$timestamp] $tool_name failed: $error" >> ~/.qoderwork/hooks/failure.log

exit 0

Config: event PostToolUseFailure, no matcher, command ~/.qoderwork/hooks/log-failure.sh.

Full Config Example

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.qoderwork/hooks/check-prompt.sh"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.qoderwork/hooks/block-dangerous.sh"
          }
        ]
      }
    ],
    "PostToolUseFailure": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.qoderwork/hooks/log-failure.sh"
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.qoderwork/hooks/notify.sh"
          }
        ]
      }
    ]
  }
}

Things to Keep in Mind

Timeout handling: Hook scripts have a default timeout of 30 seconds. If a script times out, it is killed and treated as an allow (proceed). Configurable timeouts are coming in a future release.
Error handling: If a script exits with an unexpected code (anything other than 0 or 2), the error message is shown to the user but the Agent continues without interruption.
Script permissions: Make sure your scripts are executable (chmod +x).
jq dependency: The example scripts rely on jq to parse JSON. Make sure it is installed on your system (brew install jq on macOS, apt install jq on Linux).
Restart required: After modifying ~/.qoderwork/settings.json, restart QoderWork for changes to take effect.

Best Practice Scenarios

Who Should Use Hooks

Hook value depends on your role. Here’s a quick mapping:

For Individual Developers

Scenario	Description	Practice
Prompt Enhancement	Auto-inject project-specific skills and coding standards — no manual input each time	Scenario 1
Sensitive Data Interception	Prevent passwords, keys, internal IPs from being sent to the model	Scenario 2
Dangerous Command Blocking	Block `rm -rf`, `git push --force`, and other destructive commands	Scenario 6
Harness Self-Evolution	Auto-detect reusable lessons at session end and trigger a retrospective	Scenario 8

For Teams / Enterprises

Scenario	Description	Practice
Rule/Skill Usage Analytics	Track which Rules and Skills fire across the team, assess asset quality	Scenario 3
File Edit Tracking	Record which files the Agent modifies, for change audits and impact analysis	Scenario 4
Global Usage Analytics	Collect conversation content, tool calls, model replies — full pipeline for efficiency analysis	Scenario 5
Safety Controls	Enforce a team-wide dangerous-command blocklist	Scenario 6
Quality Gates	Auto-run build/tests before the Agent finishes; block and fix if they fail	Scenario 7

QoderWork only supports user-level configuration. Add hooks to ~/.qoderwork/settings.json and keep scripts under ~/.qoderwork/hooks/. For team alignment, share hook scripts and configuration patterns in your repository or internal docs and sync them into each member’s ~/.qoderwork/ directory.

Scenario 1: Prompt Enhancement — Auto-Inject Skills

Pain point: You have to manually specify a Skill every time, or forget to load project-specific context.

Solution: Use a UserPromptSubmit hook to auto-inject a prompt hint guiding the Agent to use a specific Skill.

Config:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.qoderwork/hooks/inject-skill-hint.sh"
          }
        ]
      }
    ]
  }
}

Script ~/.qoderwork/hooks/inject-skill-hint.sh:

#!/bin/sh
# 功能：在 Prompt 提交时，注入 Skill 使用提示（每个会话仅注入一次）
INPUT=$(cat)

# === 会话级去重：同一 session 只注入一次 ===
# 可使用 SessionStart 事件替代，届时无需去重逻辑
SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty')
DEDUP_DIR="/tmp/hook-dedup"
mkdir -p "$DEDUP_DIR"

if [ -n "$SESSION_ID" ] && [ -f "$DEDUP_DIR/skill-hint-$SESSION_ID" ]; then
  exit 0  # 本会话已注入过，跳过
fi
# ============================================

# 读取项目约定的 skill 使用规则（可根据项目自定义）
SKILL_HINT=""

# === 请根据你的项目实际情况修改以下内容 ===
# 示例1：始终提示使用 git-commit skill
# SKILL_HINT="如果用户要求提交代码，请使用 /git-commit skill"

# ============================================

if [ -z "$SKILL_HINT" ]; then
  exit 0
fi

# 标记本会话已注入
[ -n "$SESSION_ID" ] && touch "$DEDUP_DIR/skill-hint-$SESSION_ID"

cat <<EOF
{"hookSpecificOutput": {"additionalContext": "$SKILL_HINT"}}
EOF

exit 0

Key points:

additionalContext is appended to the user prompt as a system-reminder injected into the Agent
Uses session_id + temp files for session-level deduplication to avoid injecting the same hint every turn
The script can read project config files for project-specific Skill recommendations
exit 0 allows the prompt through; exit 2 blocks it (e.g. for non-compliant prompts)

Scenario 2: Sensitive Prompt Blocking

Pain point: Users may accidentally include passwords, keys, internal IPs, or personal data in their prompts, risking information leakage.

Solution: Use a UserPromptSubmit hook to detect sensitive content and block the prompt.

Config:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.qoderwork/hooks/block-sensitive-prompt.sh"
          }
        ]
      }
    ]
  }
}

Script ~/.qoderwork/hooks/block-sensitive-prompt.sh:

#!/bin/sh
# 功能：检测用户 Prompt 中的敏感信息，命中则阻断
INPUT=$(cat)

# 提取用户 Prompt 内容
PROMPT=$(printf '%s' "$INPUT" | jq -r '.prompt // empty')

if [ -z "$PROMPT" ]; then
  exit 0
fi

# === 请根据团队安全规范调整敏感词规则 ===

# 1. 密钥/凭证类模式
SECRET_PATTERNS="password=|passwd=|secret_key=|access_key=|AKIA[0-9A-Z]{16}|token=[a-zA-Z0-9]{20,}"

# 2. 内部网络信息
INTERNAL_PATTERNS="10\.[0-9]+\.[0-9]+\.[0-9]+|192\.168\.|172\.(1[6-9]|2[0-9]|3[01])\." 

# 3. 自定义敏感词（团队内部术语、项目代号等）
# CUSTOM_PATTERNS="项目代号X|内部接口地址"

# 合并所有模式
ALL_PATTERNS="$SECRET_PATTERNS|$INTERNAL_PATTERNS"

# 执行检测
MATCH=$(echo "$PROMPT" | grep -oiE "$ALL_PATTERNS" | head -1)

if [ -n "$MATCH" ]; then
  echo "检测到敏感信息: $MATCH" >&2
  exit 2  # 阻断 Prompt 提交
fi

# ============================================

exit 0

Key points:

UserPromptSubmit is a blockable event; exit 2 directly prevents the prompt from reaching the Agent
Sensitive patterns support regular expressions for flexible matching (e.g. AWS AKIA prefix, internal IP ranges)
Consider extracting patterns to a separate config file (e.g. ~/.qoderwork/hooks/sensitive-patterns.txt) for team-wide maintenance
For more precise detection, call external tools like gitleaks or trufflehog

Difference from Scenario 1: Scenario 1 uses exit 0 + additionalContext for prompt enhancement (injecting context), while this scenario uses exit 2 for prompt blocking (rejecting non-compliant input). Both can coexist under the same UserPromptSubmit event and execute in config order.

Scenario 3: Rule/Skill Usage Analytics

Pain point: Many Rules and Skills are configured but actual usage rates are unknown.

Solution: Use the Transcript system + Stop hook to automatically analyze and record Rule/Skill trigger data after each conversation.

Config:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.qoderwork/hooks/analyze-rule-skill-usage.sh"
          }
        ]
      }
    ]
  }
}

Script ~/.qoderwork/hooks/analyze-rule-skill-usage.sh:

#!/bin/sh
# 功能：在 Agent 完成响应时，分析本次会话的 Rule/Skill 使用情况
INPUT=$(cat)

# 从 stdin 提取字段
TRANSCRIPT_PATH=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty')
SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty')

if [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
  exit 0
fi

# === 📝 分析逻辑 — 请根据实际需求调整 ===

# 1. 提取 session_meta 中的 rules 信息（JSONL 逐行解析）
RULES_META=$(jq -c 'select(.data.meta_type == "rules") | .data.content' "$TRANSCRIPT_PATH" 2>/dev/null | head -1)

# 2. 提取 slash_command 信息（用户通过 / 触发的 Skill）
SLASH_SKILL_META=$(jq -c 'select(.data.meta_type == "slash_command") | .data.content' "$TRANSCRIPT_PATH" 2>/dev/null | head -1)

# 3. 提取 tool_name="Skill" 的调用（Agent 主动触发的 Skill 工具调用）
#    说明：除了用户手动 /skill-name 触发外，Agent 也会自行调用 Skill 工具

AUTO_SKILL_CALLS=$(jq -c 'select(.message.content[ ]? | select(.type == "tool_use" and .name == "Skill"))' "$TRANSCRIPT_PATH" 2>/dev/null)

AUTO_SKILL_COUNT=$(printf '%s' "$AUTO_SKILL_CALLS" | grep -c . 2>/dev/null || echo 0)

AUTO_SKILL_NAMES=$(printf '%s' "$AUTO_SKILL_CALLS" | jq -r '.message.content[ ] | select(.type == "tool_use" and .name == "Skill") | .input.skill' 2>/dev/null | sort -u | jq -R -s 'split("\n") | map(select(. != ""))')


# 4. 统计全部工具调用次数

TOOL_COUNT=$(jq -c 'select(.message.content[ ]?.type == "tool_use")' "$TRANSCRIPT_PATH" 2>/dev/null | wc -l | tr -d ' ')


# 5. 记录到统计文件
STATS_DIR="$HOME/.qoderwork/stats"
mkdir -p "$STATS_DIR"
DATE=$(date +%Y-%m-%d)
STATS_FILE="$STATS_DIR/usage-${DATE}.jsonl"

jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg sid "$SESSION_ID" \
  --argjson tc "$TOOL_COUNT" \
  --argjson rules "${RULES_META:-null}" \
  --argjson slash_skill "${SLASH_SKILL_META:-null}" \
  --argjson auto_skill_count "$AUTO_SKILL_COUNT" \
  --argjson auto_skill_names "${AUTO_SKILL_NAMES:-null}" \
  '{timestamp:$ts, session_id:$sid, tool_calls:$tc, rules:$rules, slash_skill:$slash_skill, auto_skill: {count:$auto_skill_count, names:$auto_skill_names}}' >> "$STATS_FILE"

# ============================================

exit 0

Transcript auto-recorded metadata includes:

session_meta(rules): All Rules loaded in this session (name, trigger type, file path)
session_meta(slash_command): Skills used in this session (name, type, file path)
session_meta(session_info): Session mode (agent/plan) and type

Advanced usage: Write a periodic summary script to read ~/.qoderwork/stats/ JSONL files and generate Rule/Skill usage reports.

Scenario 4: File Edit Tracking

Pain point: Unclear which files the Agent modified in a session and how many times.

Solution: Use a PostToolUse hook matching file-edit tools to log every file change in real time.

Config:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|search_replace|create_file",
        "hooks": [
          {
            "type": "command",
            "command": "~/.qoderwork/hooks/track-file-changes.sh"
          }
        ]
      }
    ]
  }
}

Script ~/.qoderwork/hooks/track-file-changes.sh:

#!/bin/sh
# 功能：追踪 Agent 的文件编辑操作
INPUT=$(cat)

SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty')
TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty')
FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty')

if [ -z "$FILE_PATH" ]; then
  exit 0
fi

# === 📝 文件变更追踪逻辑 ===

# 记录变更日志
CHANGE_LOG="$HOME/.qoderwork/stats/file-changes.jsonl"
mkdir -p "$(dirname "$CHANGE_LOG")"

TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
BRANCH=$(printf '%s' "$INPUT" | jq -r '.extra.branch // empty')
REPO=$(printf '%s' "$INPUT" | jq -r '.extra.repo // empty')

echo "{\"ts\":\"$TIMESTAMP\",\"session\":\"$SESSION_ID\",\"tool\":\"$TOOL_NAME\",\"file\":\"$FILE_PATH\",\"branch\":\"$BRANCH\",\"repo\":\"$REPO\"}" >> "$CHANGE_LOG"

# ============================================

exit 0

Advanced usage:

Use additionalContext to feed change statistics back to the Agent (e.g. “15 files modified in this session”)
Integrate with your team’s code analytics system to track AI-assisted change volume

Scenario 5: Global Usage Analytics

Pain point: No quantitative data on overall Agent usage — can’t assess AI-assisted coding efficiency and quality. This includes: what questions users ask, what text the model returns, which tools are called and their results.

Solution: Use a multi-event hook combo to build full-pipeline usage data collection. UserPromptSubmit captures user questions, PostToolUse captures tool call results, Stop analyzes the complete session summary via Transcript (model replies, tool call distribution, etc.).

Config:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.qoderwork/hooks/usage-tracker.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.qoderwork/hooks/usage-tracker.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.qoderwork/hooks/usage-tracker.sh"
          }
        ]
      }
    ]
  }
}

Script ~/.qoderwork/hooks/usage-tracker.sh:

#!/bin/sh
# 功能：全局使用情况追踪（统一入口，按事件类型分发）
INPUT=$(cat)

EVENT=$(printf '%s' "$INPUT" | jq -r '.hook_event_name // empty')
SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty')
TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)

# 获取额外上下文
EMAIL=$(printf '%s' "$INPUT" | jq -r '.extra.email // empty')
REPO=$(printf '%s' "$INPUT" | jq -r '.extra.repo // empty')
BRANCH=$(printf '%s' "$INPUT" | jq -r '.extra.branch // empty')

# === 📝 数据采集逻辑 ===

STATS_DIR="$HOME/.qoderwork/stats"
mkdir -p "$STATS_DIR"
DATE=$(date +%Y-%m-%d)

case "$EVENT" in
  UserPromptSubmit)
    # 采集用户提问内容（截取前 200 字符避免日志过大）
    PROMPT=$(printf '%s' "$INPUT" | jq -r '.prompt // empty')
    PROMPT_PREVIEW=$(printf '%.200s' "$PROMPT")
    echo "{\"ts\":\"$TIMESTAMP\",\"event\":\"prompt\",\"session\":\"$SESSION_ID\",\"email\":\"$EMAIL\",\"repo\":\"$REPO\",\"branch\":\"$BRANCH\",\"prompt_preview\":\"$PROMPT_PREVIEW\"}" >> "$STATS_DIR/events-${DATE}.jsonl"
    ;;
  PostToolUse)
    TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty')
    # 采集工具调用结果（截取前 500 字符）
    TOOL_RESPONSE=$(printf '%s' "$INPUT" | jq -r '.tool_response // empty')
    TOOL_RESPONSE_PREVIEW=$(printf '%.500s' "$TOOL_RESPONSE")
    echo "{\"ts\":\"$TIMESTAMP\",\"event\":\"tool_use\",\"session\":\"$SESSION_ID\",\"tool\":\"$TOOL_NAME\",\"repo\":\"$REPO\",\"tool_response_preview\":\"$TOOL_RESPONSE_PREVIEW\"}" >> "$STATS_DIR/events-${DATE}.jsonl"
    ;;
  Stop)
    # 📊 通过 Transcript 采集完整会话摘要
    TRANSCRIPT_PATH=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty')
    SUMMARY=""
    if [ -n "$TRANSCRIPT_PATH" ] && [ -f "$TRANSCRIPT_PATH" ]; then
      USER_MSG_COUNT=$(jq -c 'select(.type == "user" and (.message.content | type == "string"))' "$TRANSCRIPT_PATH" 2>/dev/null | wc -l | tr -d ' ')
      USER_PROMPTS=$(jq -r 'select(.type == "user" and (.message.content | type == "string")) | .message.content' "$TRANSCRIPT_PATH" 2>/dev/null | head -20)

      ASSISTANT_TEXT_COUNT=$(jq -c 'select(.type == "assistant" and (.message.content[ ]? | select(.type == "text")))' "$TRANSCRIPT_PATH" 2>/dev/null | wc -l | tr -d ' ')

      ASSISTANT_TEXTS=$(jq -r 'select(.type == "assistant") | .message.content[ ]? | select(.type == "text") | .text' "$TRANSCRIPT_PATH" 2>/dev/null | head -20)

      TOOL_CALL_COUNT=$(jq -c 'select(.type == "assistant") | .message.content[ ]? | select(.type == "tool_use")' "$TRANSCRIPT_PATH" 2>/dev/null | wc -l | tr -d ' ')

      TOOL_NAMES=$(jq -r 'select(.type == "assistant") | .message.content[ ]? | select(.type == "tool_use") | .name' "$TRANSCRIPT_PATH" 2>/dev/null | sort | uniq -c | sort -rn | head -10)

      TOOL_SUCCESS=$(jq -c 'select(.type == "user") | .message.content[ ]? | select(.type == "tool_result" and .is_error == false)' "$TRANSCRIPT_PATH" 2>/dev/null | wc -l | tr -d ' ')

      TOOL_ERROR=$(jq -c 'select(.type == "user") | .message.content[ ]? | select(.type == "tool_result" and .is_error == true)' "$TRANSCRIPT_PATH" 2>/dev/null | wc -l | tr -d ' ')

      SUMMARY="user_msgs:${USER_MSG_COUNT},assistant_texts:${ASSISTANT_TEXT_COUNT},tool_calls:${TOOL_CALL_COUNT},tool_success:${TOOL_SUCCESS},tool_error:${TOOL_ERROR}"
    fi
    echo "{\"ts\":\"$TIMESTAMP\",\"event\":\"stop\",\"session\":\"$SESSION_ID\",\"repo\":\"$REPO\",\"summary\":\"$SUMMARY\"}" >> "$STATS_DIR/events-${DATE}.jsonl"

    if [ -n "$TRANSCRIPT_PATH" ] && [ -f "$TRANSCRIPT_PATH" ]; then
      SUMMARY_DIR="$STATS_DIR/sessions"
      mkdir -p "$SUMMARY_DIR"
      cat <<SUMMARY_EOF > "$SUMMARY_DIR/${SESSION_ID}.json"
{
  "session_id": "$SESSION_ID",
  "timestamp": "$TIMESTAMP",
  "repo": "$REPO",
  "branch": "$BRANCH",
  "email": "$EMAIL",
  "user_message_count": $USER_MSG_COUNT,
  "assistant_text_count": $ASSISTANT_TEXT_COUNT,
  "tool_call_count": $TOOL_CALL_COUNT,
  "tool_success": $TOOL_SUCCESS,
  "tool_error": $TOOL_ERROR,
  "tool_distribution": "$TOOL_NAMES",
  "user_prompts_preview": $(printf '%s' "$USER_PROMPTS" | head -c 2000 | jq -Rs .),
  "assistant_texts_preview": $(printf '%s' "$ASSISTANT_TEXTS" | head -c 2000 | jq -Rs .),
  "transcript_path": "$TRANSCRIPT_PATH"
}
SUMMARY_EOF
    fi
    ;;
esac

# ============================================

exit 0

Data collection dimensions:

Event	Collected Data	Source
`UserPromptSubmit`	User question (first 200 chars)	`prompt` field in stdin JSON
`PostToolUse`	Tool name + result (first 500 chars)	`tool_name` and `tool_response` fields in stdin JSON
`Stop`	Full session summary: user questions, model replies, tool call distribution, success/failure rate	JSONL file at `transcript_path`

Why analyze via Transcript in Stop? UserPromptSubmit and PostToolUse only capture data from the current interaction, while the Transcript file at Stop time contains the complete session history — enabling extraction of model reply text, tool call distribution, and success/failure rates in one pass. See Transcript File Format for details.

Scenario 6: Safety Controls — Dangerous Command Blocking

Pain point: The Agent may execute rm -rf, git push --force, or other dangerous commands.

Solution: Use a PreToolUse hook matching Bash|run_in_terminal to intercept dangerous commands before execution.

Config:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|run_in_terminal",
        "hooks": [
          {
            "type": "command",
            "command": "~/.qoderwork/hooks/block-dangerous-commands.sh"
          }
        ]
      }
    ]
  }
}

Script ~/.qoderwork/hooks/block-dangerous-commands.sh:

#!/bin/sh
# 功能：拦截危险 Shell 命令
INPUT=$(cat)

# 提取要执行的命令（从 tool_input.command 中读取）
COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty')

# === 📝 危险命令黑名单 — 请根据团队规范调整 ===
DANGEROUS_PATTERNS="rm -rf|git push --force|git push -f|DROP TABLE|DROP DATABASE|format |mkfs"

if echo "$COMMAND" | grep -qiE "$DANGEROUS_PATTERNS"; then
  echo "检测到危险命令: $COMMAND" >&2
  exit 2  # 阻断执行
fi

# ============================================

exit 0

Key points:

exit 2 immediately blocks execution; stderr content is fed back to the Agent as the block reason
The Agent will attempt an alternative (e.g. a safer command) after being blocked
For richer feedback, return JSON on stdout:

{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"Command contains rm -rf, blocked for safety"}}

Scenario 7: Quality Gate Before Agent Completion

Pain point: The Agent claims the task is done, but tests are failing or issues remain.

Solution: Use a Stop hook (blockable) to run quality checks before the Agent finishes; block and force the Agent to keep working if checks fail.

Config:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.qoderwork/hooks/quality-gate.sh",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Script ~/.qoderwork/hooks/quality-gate.sh:

#!/bin/sh
# 功能：Agent 完成前的质量门禁检查
INPUT=$(cat)

# 检查是否已经是 Stop Hook 触发的循环（防止无限循环）
STOP_HOOK_ACTIVE=$(printf '%s' "$INPUT" | jq -r '.stop_hook_active // false')
if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
  exit 0  # 已经是 Stop Hook 触发的重试，放行
fi

# === 📝 质量检查逻辑 — 请根据项目实际情况调整 ===
ERRORS=""

# 1. 检查是否有编译错误
# if ! make build 2>/dev/null; then
#   ERRORS="${ERRORS}\n- 编译失败，请修复编译错误"
# fi

# 2. 检查是否有测试失败
# if ! make test 2>/dev/null; then
#   ERRORS="${ERRORS}\n- 测试未通过，请修复失败的测试"
# fi

# 3. 检查是否有未提交的 TODO 标记
# TODO_COUNT=$(grep -r "TODO(agent)" . --include="*.go" 2>/dev/null | wc -l | tr -d ' ')
# if [ "$TODO_COUNT" -gt 0 ]; then
#   ERRORS="${ERRORS}\n- 发现 $TODO_COUNT 个未完成的 TODO 标记"
# fi

# ============================================

if [ -n "$ERRORS" ]; then
  cat <<EOF
{"decision":"block","reason":"质量检查未通过：$ERRORS\n请修复以上问题后再完成。"}
EOF
  exit 2
fi

exit 0

Key points:

stop_hook_active is used to prevent infinite loops (it is true when the Agent retries after being blocked)
After a Stop hook blocks, the block reason is injected as a user message and the Agent continues working
Set a longer timeout (e.g. 120 seconds) since builds and tests may take time

Scenario 8: Harness Self-Evolution — Automated Knowledge Sedimentation

Pain point: Lessons and decisions from each task are scattered in conversation history with no automated sedimentation process.

Solution: Use a Stop hook to automatically trigger a Harness self-evolution flow, analyzing whether the conversation produced reusable lessons and driving the asset lifecycle.

Config:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.qoderwork/hooks/harness-evolution.sh"
          }
        ]
      }
    ]
  }
}

Script ~/.qoderwork/hooks/harness-evolution.sh:

#!/bin/sh
# 功能：Agent 完成响应时，触发 Harness 自进化流程
INPUT=$(cat)

# ⚠️ 【关键】防止无限循环：检查 stop_hook_active 标志
# 当 Stop Hook 阻断 Agent 后，Agent 会重新尝试完成，此时 stop_hook_active=true
# 必须在此处放行，否则会陷入「阻断→重试→再阻断」的死循环
STOP_HOOK_ACTIVE=$(printf '%s' "$INPUT" | jq -r '.stop_hook_active // false')
if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
  exit 0  # 已经是 Stop Hook 触发的重试，直接放行
fi

TRANSCRIPT_PATH=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty')
SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // empty')

if [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
  exit 0
fi

# === 📝 Harness 自进化检测逻辑 ===

# 1. 统计本次会话的工具调用和文件变更

EDIT_COUNT=$(jq -c 'select(.message.content[ ]?.type == "tool_use")' "$TRANSCRIPT_PATH" 2>/dev/null | wc -l | tr -d ' ')


# 2. 检查是否涉及架构设计、决策讨论、规范制定等关键词
# HAS_DECISION=$(jq -r 'select(.message.content | type == "string") | .message.content' "$TRANSCRIPT_PATH" 2>/dev/null | grep -c '架构\|方案\|规范\|最佳实践' || echo 0)

# 3. 记录会话摘要到 inbox，供后续批量复盘
SEDIMENTATION_DIR="$HOME/.ai/inbox"
mkdir -p "$SEDIMENTATION_DIR"
echo "{\"session_id\":\"$SESSION_ID\",\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"tool_calls\":$EDIT_COUNT,\"transcript\":\"$TRANSCRIPT_PATH\"}" >> "$SEDIMENTATION_DIR/pending-review.jsonl"

# 4. 可选方案 A：调用外部分析总结系统
# 通过 transcript 和会话上下文调用自己的分析服务
# curl -s -X POST http://localhost:8080/api/analyze \
#   -H 'Content-Type: application/json' \
#   -d "{\"session_id\":\"$SESSION_ID\",\"transcript\":\"$TRANSCRIPT_PATH\"}" \
#   > /dev/null 2>&1 &

# 5. 可选方案 B：通过阻断触发分析总结 Skill
# 取消下面的注释，可让 Agent 被阻断后自动进入复盘 Skill 流程
# 注意：/retro 是自定义的沉淀复盘技能，你可以替换为自己团队的复盘 Skill。
# cat <<'EOF'
# {"decision":"block","reason":"任务已完成。检测到本次对话可能有值得沉淀的经验（文件变更较多）。请运行 /retro 进行复盘，提炼可复用的经验并沉淀到资产体系。"}
# EOF
# exit 2

# ============================================

exit 0

Key points:

Preventing infinite loops (mandatory): Stop hook scripts must check stop_hook_active. When the Agent retries after being blocked by a Stop hook, this field is true — exit 0 immediately to avoid an infinite loop
Use exit 2 + decision:"block" to block the Agent from completing and force a retrospective
pending-review.jsonl logs sessions for later batch review
Can be combined with a /retro Skill (custom retrospective skill) to form an auto-detect → remind → sediment closed loop

Current implementation options:

Hooks currently only support command type handlers (executing external scripts), so Harness self-evolution has two implementation paths: (A) call an external analysis service, or (B) block the Agent and trigger a retrospective Skill.

Future direction:

The hook system plans to support prompt type and agent type handlers. Once available, Harness self-evolution will upgrade from “script-driven” to “Agent-driven”, enabling true end-to-end automated knowledge sedimentation.

Transcript File Format

The Transcript is a session log file automatically generated by QoderWork, located at the path pointed to by transcript_path (e.g. ~/.qoderwork/projects/<project>/transcript/<session-id>.jsonl). Each line is an independent JSON object appended in chronological order, recording the complete session interaction.

Common Fields Per Line

Field	Type	Description
`type`	string	Record type: `session_meta` / `user` / `assistant` / `progress`
`sessionId`	string	Session ID
`uuid`	string	Unique ID for this record
`timestamp`	string	ISO 8601 timestamp
`cwd`	string	Current working directory
`message`	object	Message content (present for `user`/`assistant` types)
`data`	object	Metadata (present for `session_meta`/`progress` types)

Record Types

1. session_meta — Session metadata (first line) The first line of every Transcript file records the session’s basic information:

{
  "type": "session_meta",
  "sessionId": "86379a0e-...",
  "data": {
    "meta_type": "session_info",
    "content": {
      "mode": "agent",
      "session_type": "assistant"
    }
  }
}

data.content.mode: Session mode (agent / plan / ask / debug)
data.content.session_type: Session type (assistant / inline_chat, etc.)

2. user — User messages User messages come in two forms: User question (message.content is a string):

{
  "type": "user",
  "message": {
    "role": "user",
    "content": "Delete comments from test.py"
  }
}

Tool result (message.content is an array containing tool_result):

{
  "type": "user",
  "message": {
    "role": "user",
    "content": [
      {
        "type": "tool_result",
        "tool_use_id": "call_d498c5988a...",
        "content": "Contents of /path/to/file.py, from line 1-23 ...",
        "is_error": false
      }
    ]
  },
  "toolUseResult": "Contents of /path/to/file.py ..."
}

is_error: Whether the tool execution failed
toolUseResult: Shortcut field for the tool result (same as content[0].content)

3. assistant — Model replies Model reply message.content is always an array containing two element types: Text reply (type: "text"):

{
  "type": "assistant",
  "message": {
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "I'll help you delete comments from test.py. Let me read the file first.\n\n"
      }
    ]
  }
}

Tool call (type: "tool_use"):

{
  "type": "assistant",
  "message": {
    "role": "assistant",
    "content": [
      {
        "type": "tool_use",
        "id": "call_d498c5988a...",
        "name": "read_file",
        "input": {
          "file_path": "/path/to/file.py"
        }
      }
    ]
  }
}

name: Tool name (e.g. read_file, search_replace, run_in_terminal, Skill)
input: Tool call parameters
id: Corresponds to tool_use_id in the subsequent tool_result

4. progress — Hook trigger records Records when hook scripts fire and which commands run:

{
  "type": "progress",
  "data": {
    "type": "hook_progress",
    "hookEvent": "UserPromptSubmit",
    "hookName": "UserPromptSubmit",
    "command": "~/.qoderwork/hooks/inject-skill-hint.sh"
  }
}

Session Timeline Example

A typical session’s Transcript record order:

L1  session_meta          ← Session start, record mode and type
L2  progress              ← UserPromptSubmit Hook fires
L3  user (string)         ← User question: "Delete comments from test.py"
L4  assistant (text)      ← Model reply: "I'll help you..."
L5  assistant (tool_use)  ← Model calls read_file
L6  user (tool_result)    ← read_file returns file content
L7  assistant (text)      ← Model reply: "Now I'll delete..."
L8  assistant (tool_use)  ← Model calls search_replace
L9  user (tool_result)    ← search_replace succeeds
L10 assistant (text)      ← Model reply: "Successfully deleted..."
L11 progress              ← Stop Hook fires
L12 assistant (text)      ← Final reply after Stop Hook

Common jq Extraction Commands

TRANSCRIPT="$TRANSCRIPT_PATH"

# Extract all user questions (filter out tool results)
jq -r 'select(.type == "user" and (.message.content | type == "string")) | .message.content' "$TRANSCRIPT"

# Extract all model text replies
jq -r 'select(.type == "assistant") | .message.content[ ]? | select(.type == "text") | .text' "$TRANSCRIPT"

# Extract all tool calls (tool name + parameters)
jq -c 'select(.type == "assistant") | .message.content[ ]? | select(.type == "tool_use") | {name, input}' "$TRANSCRIPT"

# Count tool call distribution (tool name + count)
jq -r 'select(.type == "assistant") | .message.content[ ]? | select(.type == "tool_use") | .name' "$TRANSCRIPT" | sort | uniq -c | sort -rn

# Extract failed tool calls
jq -c 'select(.type == "user") | .message.content[ ]? | select(.type == "tool_result" and .is_error == true)' "$TRANSCRIPT"

# Get session mode
jq -r 'select(.type == "session_meta") | .data.content.mode' "$TRANSCRIPT"

# Get Hook trigger records
jq -c 'select(.type == "progress" and .data.type == "hook_progress") | {event: .data.hookEvent, command: .data.command}' "$TRANSCRIPT"

Design Principles

Principle	Description
Fail fast	Hook scripts should be lightweight to avoid blocking the Agent’s main flow
Graceful degradation	Abnormal exit codes (not 0 or 2) do not block the Agent, ensuring fault tolerance
Single responsibility	Each script does one thing; combine multiple hooks for complex logic
Idempotent design	The same event may fire multiple times; scripts should be idempotent
Loop prevention	Stop hooks must check `stop_hook_active` to prevent infinite retries

Recommended Hook Combinations

Goal	Recommended Combination
Safety controls	`PreToolUse(Bash)` dangerous command blocking
Quality assurance	`Stop` quality gate
Data-driven insights	`UserPromptSubmit` + `PostToolUse` + `Stop` full-pipeline collection
Harness self-evolution	`Stop` sedimentation detection + `UserPromptSubmit` Skill guidance
Team collaboration	Shared conventions: same hook patterns in `~/.qoderwork/settings.json` and scripts under `~/.qoderwork/hooks/`, documented in your team wiki or dotfiles repo

Debugging Guide

Step 1: Confirm the Hook Fires

When a hook does not fire as expected, add debug logging at the very start of the script:

#!/bin/sh
# ===== Debug mode: confirm hook fires =====
INPUT=$(cat)
printf '[HOOK DEBUG] %s hook triggered, event=%s\n' "$(date '+%H:%M:%S')" "$(printf '%s' "$INPUT" | jq -r '.hook_event_name')" >> /tmp/hook-debug.log
printf '%s' "$INPUT" | jq . >> /tmp/hook-debug.log
echo "---" >> /tmp/hook-debug.log
# ===== Remove debug code when done =====

# ... your actual logic ...
exit 0

Then trigger an Agent operation and check the log:

$ tail -f /tmp/hook-debug.log
[HOOK DEBUG] 14:32:01 hook triggered, event=PreToolUse
{
  "session_id": "abc123",
  "hook_event_name": "PreToolUse",
  "tool_name": "run_in_terminal",
  "tool_input": {
    "command": "ls -la"
  },
  ...
}
---

Troubleshooting: If no output appears, the hook is not firing. Check your config file location, event name, matcher pattern, and script path.

Step 2: Reproduce Locally with Real Input

Use the JSON captured in Step 1 to test the script outside of QoderWork:

# Pipe the captured input to simulate stdin
$ cat /tmp/hook-debug.json | sh ~/.qoderwork/hooks/pre-tool-check.sh
$ echo $?   # Check exit code: 0=allow, 2=block

# Or manually construct test input
$ echo '{"hook_event_name":"PreToolUse","tool_name":"run_in_terminal","tool_input":{"command":"rm -rf /"}}' | sh ~/.qoderwork/hooks/pre-tool-check.sh
$ echo $?   # Expected: 2 (block dangerous command)

Tip: Save common test cases as files for repeated validation.

Step 3: Other Debugging Methods

Check the Transcript: ~/.qoderwork/projects/<encoded-path>/transcript/<session>.jsonl — parse with jq line by line
Check Hook logs: Search for [hook] prefix in QoderWork logs for execution results and timing
Start simple: First verify the hook fires with a bare exit 0, then add business logic incrementally
Clean up: Remove debug code (/tmp/hook-debug.log writes) after debugging to avoid performance impact

Quick Start Template

Minimal Config

Save the following to ~/.qoderwork/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.qoderwork/hooks/pre-tool-check.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "~/.qoderwork/hooks/post-edit-track.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.qoderwork/hooks/on-stop.sh"
          }
        ]
      }
    ]
  }
}

User directory structure

~/.qoderwork/
├── settings.json    ← Hook configuration
└── hooks/           ← Hook scripts
    ├── pre-tool-check.sh
    ├── post-edit-track.sh
    └── on-stop.sh

Get Started

User Guide

Extensions

Best Practices

​Quick Start

​How It Works

​Prerequisites

​Creating Hooks

​1. Decide What You Need: Pick an Event and a Matcher

​2. Write the Hook Script

​3. Register the Script in Your Config

​4. Test and Debug

​Configuring Hooks

​Config File Location

​Config Format

​Matcher Rules

​Tool Name Mapping

​Writing Hook Scripts

​Input

​Output

​Hook Events

​UserPromptSubmit

​PreToolUse

​PostToolUse

​PostToolUseFailure

​Stop

​SessionStart

​SessionEnd

​SubagentStart / SubagentStop

​PreCompact

​Notification

​PermissionRequest

​Scenario Examples

​Block Dangerous Commands

​Keep Agent Working

​Inject Context on Prompt Submit

​Desktop Notification on Events

​Prompt Content Screening

​Log Tool Failures

​Full Config Example

​Things to Keep in Mind

​Best Practice Scenarios

​Who Should Use Hooks

​For Individual Developers

​For Teams / Enterprises

​Scenario 1: Prompt Enhancement — Auto-Inject Skills

​Scenario 2: Sensitive Prompt Blocking

​Scenario 3: Rule/Skill Usage Analytics

​Scenario 4: File Edit Tracking

​Scenario 5: Global Usage Analytics

​Scenario 6: Safety Controls — Dangerous Command Blocking

​Scenario 7: Quality Gate Before Agent Completion

​Scenario 8: Harness Self-Evolution — Automated Knowledge Sedimentation

​Transcript File Format

​Common Fields Per Line

​Record Types

​Session Timeline Example

​Common jq Extraction Commands

​Design Principles

​Recommended Hook Combinations

​Debugging Guide

​Step 1: Confirm the Hook Fires

​Step 2: Reproduce Locally with Real Input

​Step 3: Other Debugging Methods

​Quick Start Template

​Minimal Config

​User directory structure

Quick Start

How It Works

Prerequisites

Creating Hooks

1. Decide What You Need: Pick an Event and a Matcher

2. Write the Hook Script

3. Register the Script in Your Config

4. Test and Debug

Configuring Hooks

Config File Location

Config Format

Matcher Rules

Tool Name Mapping

Writing Hook Scripts

Input

Output

Hook Events

UserPromptSubmit

PreToolUse

PostToolUse

PostToolUseFailure

Stop

SessionStart

SessionEnd

SubagentStart / SubagentStop

PreCompact

Notification

PermissionRequest

Scenario Examples

Block Dangerous Commands

Keep Agent Working

Inject Context on Prompt Submit

Desktop Notification on Events

Prompt Content Screening

Log Tool Failures

Full Config Example

Things to Keep in Mind

Best Practice Scenarios

Who Should Use Hooks

For Individual Developers

For Teams / Enterprises

Scenario 1: Prompt Enhancement — Auto-Inject Skills

Scenario 2: Sensitive Prompt Blocking

Scenario 3: Rule/Skill Usage Analytics

Scenario 4: File Edit Tracking

Scenario 5: Global Usage Analytics

Scenario 6: Safety Controls — Dangerous Command Blocking

Scenario 7: Quality Gate Before Agent Completion

Scenario 8: Harness Self-Evolution — Automated Knowledge Sedimentation

Transcript File Format

Common Fields Per Line

Record Types

Session Timeline Example

Common jq Extraction Commands

Design Principles

Recommended Hook Combinations

Debugging Guide

Step 1: Confirm the Hook Fires

Step 2: Reproduce Locally with Real Input

Step 3: Other Debugging Methods

Quick Start Template

Minimal Config

User directory structure