Hook and tool names

The tool names, hook events, environment variables, and contract details each harness uses, generated from the shipped catalogs in pkg/harness-compilation/toolpolicy and pkg/harness-compilation/hookpolicy. Regenerate with make catalog-docs; make catalog-check fails when this page is stale.

Shared tool concepts

Concept	Meaning
access.request	Ask the user for filesystem access.
ask.user	Ask the user a question.
file.delete	Delete a file.
file.edit	Modify an existing file in place, including patch application.
file.list	List a directory.
file.read	Read file contents.
file.write	Create or overwrite a whole file.
mcp.call	Call a tool on an MCP server.
mcp.read	Read an MCP resource.
mcp.servers	List configured MCP servers.
mcp.tools	List tools on MCP servers.
notebook.edit	Modify notebook cells.
notebook.read	Read notebook cells.
plan.enter	Enter plan mode.
plan.exit	Leave plan mode.
search.glob	Find files by path pattern.
search.grep	Search file contents.
shell	Run a shell command.
shell.powershell	Run a PowerShell command.
shell.session	Poll, feed, or stop an already running shell session.
skill	Load a skill.
subagent	Start a subagent.
subagent.read	Read a running subagent's output.
todo	Maintain the agent's task list.
web.fetch	Fetch a URL.
web.search	Run a web search.

Canonical hook events

Canonical event	Meaning
Notification	When the harness sends a user notification.
PermissionRequest	When a tool call needs a permission decision.
PostCompact	After context compaction.
PostToolUse	After a tool call succeeds.
PostToolUseFailure	After a tool call fails.
PreCompact	Before context compaction.
PreToolUse	Before a tool call runs; can block it.
SessionEnd	When a session ends.
SessionStart	When a session starts or resumes.
Stop	When the main agent is about to finish its turn; can request continuation.
SubagentStart	When a subagent starts.
SubagentStop	When a subagent finishes.
UserPromptSubmit	After the user submits a prompt, before the model sees it.

Tool names by harness

claude

Surfaces: hook_matcher, subagent_tools, skill_allowed_tools. MCP naming: mcp__{server}__{tool}; match-all mcp__.*; server scoped: true.

Tool	Concepts	Aliases	Surfaces
Agent	subagent	Task	all
AskUserQuestion	ask.user	-	all
Bash	shell	-	all
Edit	file.edit	MultiEdit	all
EnterPlanMode	plan.enter	-	all
ExitPlanMode	plan.exit	-	all
Glob	search.glob	-	all
Grep	search.grep	-	all
NotebookEdit	notebook.edit	-	all
PowerShell	shell.powershell	-	all
Read	file.read	-	all
Skill	skill	-	all
TodoWrite	todo	-	all
WebFetch	web.fetch	-	all
WebSearch	web.search	-	all
Write	file.write	-	all

codex

Surfaces: hook_matcher. MCP naming: mcp__{server}__{tool}; match-all mcp__.*; server scoped: true.

Tool	Concepts	Aliases	Surfaces
Bash	shell	-	all
apply_patch	file.write, file.edit	Edit, Write	all
spawn_agent	subagent	Agent	all
update_plan	todo	-	all

cursor

Surfaces: hook_matcher. MCP naming: MCP:{tool}; match-all MCP:.*; server scoped: false.

Tool	Concepts	Aliases	Surfaces
Delete	file.delete	-	all
Grep	search.grep	-	all
Read	file.read	-	all
Shell	shell	-	all
Task	subagent	-	all
WebFetch	web.fetch	-	all
WebSearch	web.search	-	all
Write	file.write, file.edit	-	all

devin

Surfaces: hook_matcher, subagent_tools, skill_allowed_tools. MCP naming: mcp__{server}__{tool}; match-all mcp__.*; server scoped: true.

Tool	Concepts	Aliases	Surfaces
apply_patch	file.write, file.edit	-	hook_matcher
edit	file.edit	-	all
exec	shell	-	all
exit_plan_mode	plan.exit	-	hook_matcher
get_output	shell.session	-	hook_matcher
glob	search.glob	-	all
grep	search.grep	-	all
kill_shell	shell.session	-	hook_matcher
mcp_call_tool	mcp.call	-	hook_matcher
mcp_list_servers	mcp.servers	-	hook_matcher
mcp_list_tools	mcp.tools	-	hook_matcher
mcp_read_resource	mcp.read	-	hook_matcher
notebook_edit	notebook.edit	-	hook_matcher
notebook_read	notebook.read	-	hook_matcher
read	file.read	-	all
read_subagent	subagent.read	-	hook_matcher
request_scope	access.request	-	hook_matcher
run_subagent	subagent	-	hook_matcher
skill	skill	-	hook_matcher
todo_write	todo	-	hook_matcher
webfetch	web.fetch	-	hook_matcher
write	file.write	-	hook_matcher
write_to_process	shell.session	-	hook_matcher

factory

Surfaces: hook_matcher, subagent_tools. MCP naming: mcp__{server}__{tool}; match-all mcp__.*; server scoped: true.

Tool	Concepts	Aliases	Surfaces
ApplyPatch	file.write, file.edit	-	all
Create	file.write	-	all
Edit	file.edit	-	all
Execute	shell	-	all
FetchUrl	web.fetch	-	all
Glob	search.glob	-	all
Grep	search.grep	-	all
LS	file.list	-	all
Read	file.read	-	all
Skill	skill	-	hook_matcher
Task	subagent	-	hook_matcher
TodoWrite	todo	-	hook_matcher
WebSearch	web.search	-	all

gemini

Surfaces: hook_matcher, subagent_tools. MCP naming: mcp_{server}_{tool}; match-all mcp_.*; server scoped: true.

Tool	Concepts	Aliases	Surfaces
activate_skill	skill	-	all
ask_user	ask.user	-	all
enter_plan_mode	plan.enter	-	all
exit_plan_mode	plan.exit	-	all
glob	search.glob	-	all
google_web_search	web.search	-	all
grep_search	search.grep	search_file_content	all
list_directory	file.list	-	all
read_file	file.read	-	all
read_many_files	file.read	-	all
replace	file.edit	-	all
run_shell_command	shell	-	all
web_fetch	web.fetch	-	all
write_file	file.write	-	all
write_todos	todo	-	all

opencode

Surfaces: hook_matcher. MCP naming: ``; match-all mcp_.*; server scoped: false.

Tool	Concepts	Aliases	Surfaces
apply_patch	file.write, file.edit	-	all
bash	shell	Bash	all
edit	file.edit	Edit	all
glob	search.glob	Glob	all
grep	search.grep	Grep	all
question	ask.user	-	all
read	file.read	Read	all
skill	skill	Skill	all
task	subagent	Task	all
todowrite	todo	TodoWrite	all
webfetch	web.fetch	WebFetch	all
websearch	web.search	WebSearch	all
write	file.write	Write	all

windsurf

Surfaces: none. MCP naming: ``; match-all *; server scoped: false.

No tool-name vocabulary: tool selection is encoded in the hook event.

Hook contracts by harness

claude

Timeout unit: seconds. Matcher syntax: exact-or-regex (exact |/, lists). Repository base: env project_dir.

Variable concept	Names	Events
env_file	CLAUDE_ENV_FILE	SessionStart, Setup, CwdChanged, FileChanged
project_dir	CLAUDE_PROJECT_DIR	all
remote	CLAUDE_CODE_REMOTE	all
plugin_data (plugin only)	CLAUDE_PLUGIN_DATA	all
plugin_root (plugin only)	CLAUDE_PLUGIN_ROOT	all

Event	Canonical	Matcher	Types	Timeout bounds
ConfigChange	(native only)	lifecycle	command, http, mcp_tool	-
CwdChanged	(native only)	none	command, http, mcp_tool	-
DirectoryAdded	(native only)	lifecycle	command, http, mcp_tool	-
Elicitation	(native only)	lifecycle	command, http, mcp_tool	-
ElicitationResult	(native only)	lifecycle	command, http, mcp_tool	-
FileChanged	(native only)	lifecycle	command, http, mcp_tool	-
InstructionsLoaded	(native only)	lifecycle	command, http, mcp_tool	-
MessageDisplay	(native only)	none	command, http, mcp_tool	-
Notification	Notification	lifecycle	command, http, mcp_tool	-
PermissionDenied	(native only)	tool	command, http, mcp_tool, prompt, agent	-
PermissionRequest	PermissionRequest	tool	command, http, mcp_tool, prompt	-
PostCompact	PostCompact	lifecycle	command, http, mcp_tool	-
PostModelSwitch	(native only)	lifecycle	command, http, mcp_tool	-
PostToolBatch	(native only)	none	command, http, mcp_tool, prompt, agent	-
PostToolUse	PostToolUse	tool	command, http, mcp_tool, prompt, agent	-
PostToolUseFailure	PostToolUseFailure	tool	command, http, mcp_tool, prompt, agent	-
PreCompact	PreCompact	lifecycle	command, http, mcp_tool	-
PreModelSwitch	(native only)	lifecycle	command, http, mcp_tool	-
PreToolUse	PreToolUse	tool	command, http, mcp_tool, prompt, agent	-
SessionEnd	SessionEnd	lifecycle	command, http, mcp_tool	-
SessionStart	SessionStart	lifecycle	command, mcp_tool	-
Setup	(native only)	lifecycle	command	-
Stop	Stop	none	command, http, mcp_tool, prompt, agent	-
StopFailure	(native only)	lifecycle	command, http, mcp_tool	-
SubagentStart	SubagentStart	lifecycle	command, http, mcp_tool	-
SubagentStop	SubagentStop	lifecycle	command, http, mcp_tool, prompt, agent	-
TaskCompleted	(native only)	none	command, http, mcp_tool, prompt, agent	-
TaskCreated	(native only)	none	command, http, mcp_tool, prompt, agent	-
TeammateIdle	(native only)	none	command, http, mcp_tool, prompt, agent	-
UserPromptExpansion	(native only)	lifecycle	command, http, mcp_tool, prompt, agent	-
UserPromptSubmit	UserPromptSubmit	none	command, http, mcp_tool, prompt, agent	-
WorktreeCreate	(native only)	none	command, http, mcp_tool	-
WorktreeRemove	(native only)	none	command, http, mcp_tool	-

codex

Timeout unit: seconds. Matcher syntax: regex (output anchored). Repository base: shell "$(git rev-parse --show-toplevel)".

Variable concept	Names	Events
plugin_data (plugin only)	PLUGIN_DATA, CLAUDE_PLUGIN_DATA	all
plugin_root (plugin only)	PLUGIN_ROOT, CLAUDE_PLUGIN_ROOT	all

Event	Canonical	Matcher	Types	Timeout bounds
Interrupt	(native only)	none	command, mcp_tool	1-3
PermissionRequest	(native only)	tool	command, mcp_tool	-
PostCompact	(native only)	lifecycle	command, mcp_tool	-
PostToolUse	PostToolUse	tool	command, mcp_tool	-
PreCompact	(native only)	lifecycle	command, mcp_tool	-
PreToolUse	PreToolUse	tool	command, mcp_tool	-
SessionEnd	(native only)	lifecycle	command	1-3
SessionStart	SessionStart	lifecycle	command, mcp_tool	-
Stop	Stop	none	command, mcp_tool	-
SubagentStart	(native only)	lifecycle	command, mcp_tool	-
SubagentStop	(native only)	lifecycle	command, mcp_tool	-
UserPromptSubmit	UserPromptSubmit	none	command, mcp_tool	-

cursor

Timeout unit: seconds. Matcher syntax: regex. Repository base: env project_dir. Also loads hooks of: claude.

Variable concept	Names	Events
project_dir	CURSOR_PROJECT_DIR, CLAUDE_PROJECT_DIR	all
remote	CURSOR_CODE_REMOTE	all
transcript_path	CURSOR_TRANSCRIPT_PATH	all
user_email	CURSOR_USER_EMAIL	all
version	CURSOR_VERSION	all
plugin_root (plugin only)	CURSOR_PLUGIN_ROOT	all

Event	Canonical	Matcher	Types	Timeout bounds
afterAgentResponse	(native only)	lifecycle	command, prompt	-
afterAgentThought	(native only)	lifecycle	command, prompt	-
afterFileEdit	(native only)	tool	command, prompt	-
afterMCPExecution	(native only)	none	command, prompt	-
afterShellExecution	(native only)	command_text	command, prompt	-
afterTabFileEdit	(native only)	lifecycle	command, prompt	-
beforeMCPExecution	(native only)	none	command, prompt	-
beforeReadFile	(native only)	tool	command, prompt	-
beforeShellExecution	(native only)	command_text	command, prompt	-
beforeSubmitPrompt	UserPromptSubmit	lifecycle	command, prompt	-
beforeTabFileRead	(native only)	lifecycle	command, prompt	-
postToolUse	PostToolUse	tool	command, prompt	-
postToolUseFailure	(native only)	tool	command, prompt	-
preCompact	PreCompact	none	command, prompt	-
preToolUse	PreToolUse	tool	command, prompt	-
sessionEnd	SessionEnd	none	command, prompt	-
sessionStart	SessionStart	none	command, prompt	-
stop	Stop	lifecycle	command, prompt	-
subagentStart	(native only)	lifecycle	command, prompt	-
subagentStop	SubagentStop	lifecycle	command, prompt	-
workspaceOpen	(native only)	none	command, prompt	-

devin

Timeout unit: seconds. Matcher syntax: regex (output anchored). Repository base: env project_dir. Also loads hooks of: claude.

Variable concept	Names	Events
project_dir	DEVIN_PROJECT_DIR	all

Event	Canonical	Matcher	Types	Timeout bounds
PermissionRequest	PermissionRequest	tool	command, prompt	-
PostCompaction	PostCompact	none	command, prompt	-
PostToolUse	PostToolUse	tool	command, prompt	-
PreToolUse	PreToolUse	tool	command, prompt	-
SessionEnd	SessionEnd	none	command, prompt	-
SessionStart	SessionStart	none	command, prompt	-
Stop	Stop	none	command, prompt	-
UserPromptSubmit	UserPromptSubmit	none	command, prompt	-

factory

Timeout unit: seconds. Matcher syntax: exact-or-regex. Repository base: env project_dir.

Variable concept	Names	Events
project_dir	FACTORY_PROJECT_DIR	all
plugin_root (plugin only)	DROID_PLUGIN_ROOT, CLAUDE_PLUGIN_ROOT	all

Event	Canonical	Matcher	Types	Timeout bounds
Notification	Notification	lifecycle	command	-
PostToolUse	PostToolUse	tool	command	-
PreCompact	PreCompact	lifecycle	command	-
PreToolUse	PreToolUse	tool	command	-
SessionEnd	SessionEnd	lifecycle	command	-
SessionStart	SessionStart	lifecycle	command	-
Stop	Stop	none	command	-
SubagentStop	SubagentStop	lifecycle	command	-
UserPromptSubmit	UserPromptSubmit	none	command	-

gemini

Timeout unit: milliseconds. Matcher syntax: regex. Repository base: env project_dir.

Variable concept	Names	Events
cwd	GEMINI_CWD	all
plans_dir	GEMINI_PLANS_DIR	all
project_dir	GEMINI_PROJECT_DIR, CLAUDE_PROJECT_DIR	all
session_id	GEMINI_SESSION_ID	all
plugin_root (plugin only)	extensionPath	all

Event	Canonical	Matcher	Types	Timeout bounds
AfterAgent	Stop	none	command	-
AfterModel	(native only)	none	command	-
AfterTool	PostToolUse	tool	command	-
BeforeAgent	UserPromptSubmit	none	command	-
BeforeModel	(native only)	none	command	-
BeforeTool	PreToolUse	tool	command	-
BeforeToolSelection	(native only)	none	command	-
Notification	Notification	lifecycle	command	-
PreCompress	PreCompact	lifecycle	command	-
SessionEnd	SessionEnd	lifecycle	command	-
SessionStart	SessionStart	lifecycle	command	-

opencode

Timeout unit: seconds. Matcher syntax: exact-or-regex (exact |/, lists). Repository base: env project_dir.

Variable concept	Names	Events
project_dir	AGENT_MARKETPLACE_PROJECT_DIR	all

Event	Canonical	Matcher	Types	Timeout bounds
PreToolUse	PreToolUse	tool	command	-

windsurf

Timeout unit: none. Matcher syntax: none. Repository base: cwd repository.

Variable concept	Names	Events
workspace_root	ROOT_WORKSPACE_PATH	post_setup_worktree

Event	Canonical	Matcher	Types	Timeout bounds
post_cascade_response	Stop		command	-
post_cascade_response_with_transcript	(native only)		command	-
post_mcp_tool_use	PostToolUse	(mcp)	command	-
post_read_code	PostToolUse	[file.read]	command	-
post_run_command	PostToolUse	[shell]	command	-
post_setup_worktree	(native only)		command	-
post_write_code	PostToolUse	[file.write, file.edit]	command	-
pre_mcp_tool_use	PreToolUse	(mcp)	command	-
pre_read_code	PreToolUse	[file.read]	command	-
pre_run_command	PreToolUse	[shell]	command	-
pre_user_prompt	UserPromptSubmit		command	-
pre_write_code	PreToolUse	[file.write, file.edit]	command	-