hooks

Documentation

Index

• Variables

Variables

var ClaudeHookPayload = Type("ClaudeHookPayload", func() {
	Description("Unified payload for all Claude Code hook events")
	Required("hook_event_name")
	Attribute("hook_event_name", String, "The type of hook event", func() {
		Enum("SessionStart", "PreToolUse", "PostToolUse", "PostToolUseFailure",
			"UserPromptSubmit", "Stop", "SessionEnd", "Notification")
	})

	Attribute("tool_name", String, "The name of the tool (for tool-related events)")
	Attribute("tool_use_id", String, "The unique ID for this tool use")
	Attribute("tool_input", Any, "The input to the tool")
	Attribute("tool_response", Any, "The response from the tool (PostToolUse only)")
	Attribute("error", Any, "The error from the tool (PostToolUseFailure only)")
	Attribute("is_interrupt", Boolean, "Whether the failure was caused by user interruption (PostToolUseFailure only)")

	Attribute("session_id", String, "The Claude Code session ID")
	Attribute("cwd", String, "The working directory when the event fired")
	Attribute("transcript_path", String, "Path to the conversation transcript file")
	Attribute("additional_data", MapOf(String, Any), "Additional hook-specific data")

	Attribute("source", String, "How the session started: startup, resume, clear, compact (SessionStart only)")
	Attribute("model", String, "The model identifier (SessionStart, Stop)")

	Attribute("prompt", String, "The user's prompt text (UserPromptSubmit only)")

	Attribute("last_assistant_message", String, "Claude's final response text (Stop only)")
	Attribute("stop_hook_active", Boolean, "Whether a stop hook continuation is active (Stop only)")

	Attribute("reason", String, "Why the session ended (SessionEnd only)")

	Attribute("notification_type", String, "Type of notification: permission_prompt, idle_prompt, auth_success, elicitation_dialog (Notification only)")
	Attribute("message", String, "Notification message text (Notification only)")
	Attribute("title", String, "Notification title (Notification only)")
})

Unified Claude Code hook payload

var ClaudeHookResult = Type("ClaudeHookResult", func() {
	Description("Unified result for all Claude Code hook events with proper response structure")
	Attribute("continue", Boolean, "Whether to continue (SessionStart only)")
	Attribute("stopReason", String, "Reason if blocked (SessionStart only)")
	Attribute("suppressOutput", Boolean, "Whether to suppress the hook's output")
	Attribute("systemMessage", String, "Warning message shown to the user in the terminal")
	Attribute("hookSpecificOutput", Any, "Hook-specific output as JSON object")
})

Unified Claude Code hook result with proper hook response structure

var CodexHookPayload = Type("CodexHookPayload", func() {
	Description("Payload for Codex hook events")
	Required("hook_event_name")
	Attribute("hook_event_name", String, "The type of hook event", func() {
		Enum("SessionStart", "PreToolUse", "PermissionRequest", "PostToolUse", "UserPromptSubmit", "Stop")
	})
	Attribute("session_id", String, "The Codex session ID")
	Attribute("transcript_path", String, "Path to the conversation transcript file")
	Attribute("cwd", String, "The working directory when the event fired")
	Attribute("model", String, "The model identifier")

	Attribute("tool_name", String, "The name of the tool")
	Attribute("tool_input", Any, "The input to the tool (PreToolUse only)")
	Attribute("tool_output", Any, "The output from the tool (PostToolUse only)")

	Attribute("permission_type", String, "The type of permission being requested (PermissionRequest only)")

	Attribute("prompt", String, "The user's prompt text (UserPromptSubmit only)")
})

Codex hook payload

var CodexHookResult = Type("CodexHookResult", func() {
	Description("Result for Codex hook events")
	Attribute("decision", String, "Permission decision for blocking events: allow or deny")
	Attribute("reason", String, "Reason for the decision, shown to the user")
})

Codex hook result

var CursorHookPayload = Type("CursorHookPayload", func() {
	Description("Payload for Cursor hook events")
	Required("hook_event_name")
	Attribute("hook_event_name", String, "The type of hook event (e.g. beforeSubmitPrompt, stop, afterAgentResponse, afterAgentThought, preToolUse, postToolUse, postToolUseFailure, beforeMCPExecution, afterMCPExecution)")
	Attribute("conversation_id", String, "The Cursor conversation ID")
	Attribute("generation_id", String, "The Cursor generation ID")
	Attribute("model", String, "The model being used")
	Attribute("cursor_version", String, "The Cursor IDE version")
	Attribute("user_email", String, "Email of the authenticated Cursor user, if available")
	Attribute("session_id", String, "The session ID from Cursor")
	Attribute("tool_name", String, "The name of the tool")
	Attribute("tool_use_id", String, "The unique ID for this tool use")
	Attribute("tool_input", Any, "The input to the tool")
	Attribute("tool_response", Any, "The response from the tool (postToolUse only)")
	Attribute("error", Any, "The error from the tool (postToolUseFailure only)")
	Attribute("is_interrupt", Boolean, "Whether the failure was caused by user interruption")
	Attribute("additional_data", MapOf(String, Any), "Additional hook-specific data")

	Attribute("prompt", String, "The user's prompt text (beforeSubmitPrompt only)")
	Attribute("composer_mode", String, "The composer mode, e.g. agent (beforeSubmitPrompt only)")
	Attribute("transcript_path", String, "Path to the conversation transcript JSONL file")

	Attribute("status", String, "Completion status, e.g. completed (stop only)")
	Attribute("loop_count", Int, "Number of agentic loops executed (stop only)")
	Attribute("input_tokens", Int, "Total input tokens used (stop, afterAgentResponse)")
	Attribute("output_tokens", Int, "Total output tokens used (stop, afterAgentResponse)")
	Attribute("cache_read_tokens", Int, "Tokens read from cache (stop, afterAgentResponse)")
	Attribute("cache_write_tokens", Int, "Tokens written to cache (stop, afterAgentResponse)")

	Attribute("text", String, "The assistant's response text (afterAgentResponse) or thinking text (afterAgentThought)")
	Attribute("duration_ms", Int, "Duration in milliseconds for the thinking block (afterAgentThought only)")

	Attribute("url", String, "URL of the MCP server (beforeMCPExecution / afterMCPExecution, URL-based servers only)")
	Attribute("command", String, "Command string for command-based MCP servers (beforeMCPExecution / afterMCPExecution only)")
	Attribute("result_json", String, "JSON-encoded string of the MCP tool response (afterMCPExecution only)")
	Attribute("duration", Float64, "Execution duration in milliseconds, excluding approval wait time (afterMCPExecution only)")
})

Cursor hook payload

var CursorHookResult = Type("CursorHookResult", func() {
	Description("Result for Cursor hook events")
	Attribute("permission", String, "Permission decision for preToolUse / beforeMCPExecution: allow, deny, or ask")
	Attribute("user_message", String, "Message to display to the user")
	Attribute("additional_context", String, "Additional context to inject into the conversation")
	Attribute("agent_message", String, "Message sent back to the agent (beforeMCPExecution only)")
})

Cursor hook result

var OTELAttribute = Type("OTELAttribute", func() {
	Description("OTEL log attribute with key and typed value")
	Required("key")
	Attribute("key", String, "Attribute key")
	Attribute("value", OTELAttributeValue, "Attribute value")
})

OTEL attribute with key-value pair

var OTELAttributeValue = Type("OTELAttributeValue", func() {
	Description("OTEL attribute value - any of the OTLP/JSON value kinds")
	Attribute("stringValue", String, "String value")
	Attribute("intValue", Any, "Integer value (string-encoded per OTLP/JSON, or raw number)")
	Attribute("boolValue", Boolean, "Boolean value")
	Attribute("doubleValue", Float64, "Double value")
	Attribute("arrayValue", Any, "Array value (passed through)")
	Attribute("kvlistValue", Any, "Key-value list value (passed through)")
	Attribute("bytesValue", String, "Bytes value (base64-encoded per OTLP/JSON)")
})

OTEL attribute value supporting all OTLP/JSON value kinds.

intValue is Any (not Int64 or String) because real producers disagree: canonical OTLP/JSON encodes int64 as a JSON string ("12345"), while some non-conformant emitters (including Claude Code's own exporter) ship raw numbers (12345). Handlers coerce with parseLooseInt64.

var OTELLogBody = Type("OTELLogBody", func() {
	Description("OTEL log body")
	Attribute("stringValue", String, "String body value")
})

OTEL log body

var OTELLogRecord = Type("OTELLogRecord", func() {
	Description("Individual OTEL log record")
	Attribute("timeUnixNano", String, "Timestamp in nanoseconds since Unix epoch")
	Attribute("observedTimeUnixNano", String, "Observed timestamp in nanoseconds")
	Attribute("body", OTELLogBody, "Log body content")
	Attribute("attributes", ArrayOf(OTELAttribute), "Log attributes")
	Attribute("droppedAttributesCount", Int, "Number of dropped attributes")
})

OTEL log record

var OTELLogsPayload = Type("OTELLogsPayload", func() {
	Description("OTEL logs export payload")
	Attribute("resourceLogs", ArrayOf(OTELResourceLog), "Array of resource logs")
})

OTEL logs payload

var OTELMetric = Type("OTELMetric", func() {
	Description("OTEL metric")
	Attribute("name", String, "Metric name")
	Attribute("description", String, "Metric description")
	Attribute("unit", String, "Metric unit")
	Attribute("sum", OTELSum, "Sum metric data")
	Attribute("gauge", Any, "Gauge metric data (passed through)")
	Attribute("histogram", Any, "Histogram metric data (passed through)")
	Attribute("exponentialHistogram", Any, "ExponentialHistogram metric data (passed through)")
	Attribute("summary", Any, "Summary metric data (passed through)")
})

OTEL metric. Gauge/Histogram/Summary kinds are accepted opaquely so unknown metric shapes don't fail the whole batch — they're simply skipped downstream.

var OTELMetricsPayload = Type("OTELMetricsPayload", func() {
	Description("OTEL metrics export payload")
	Attribute("resourceMetrics", ArrayOf(OTELResourceMetrics), "Array of resource metrics")
})

OTEL metrics payload

var OTELNumberDataPoint = Type("OTELNumberDataPoint", func() {
	Description("OTEL number data point")
	Attribute("attributes", ArrayOf(OTELAttribute), "Data point attributes")
	Attribute("startTimeUnixNano", String, "Start timestamp in nanoseconds")
	Attribute("timeUnixNano", String, "Timestamp in nanoseconds")
	Attribute("asDouble", Float64, "Value as double")
	Attribute("asInt", Any, "Value as integer (string-encoded per OTLP/JSON, or raw number)")
})

OTEL number data point.

asInt is Any because OTLP/JSON producers disagree on encoding: canonical OTLP/JSON ships int64 as a string ("12345"), but some emitters (Claude Code's own exporter included) ship raw numbers. Handlers coerce with parseLooseInt64.

var OTELResource = Type("OTELResource", func() {
	Description("OTEL resource information")
	Attribute("attributes", ArrayOf(OTELResourceAttribute), "Resource attributes")
	Attribute("droppedAttributesCount", Int, "Number of dropped attributes")
})

OTEL resource

var OTELResourceAttribute = Type("OTELResourceAttribute", func() {
	Description("OTEL resource attribute")
	Required("key")
	Attribute("key", String, "Resource attribute key")
	Attribute("value", OTELAttributeValue, "Resource attribute value")
})

OTEL resource attribute

var OTELResourceLog = Type("OTELResourceLog", func() {
	Description("OTEL resource logs container")
	Attribute("resource", OTELResource, "Resource information")
	Attribute("scopeLogs", ArrayOf(OTELScopeLog), "Array of scope logs")
})

OTEL resource logs

var OTELResourceMetrics = Type("OTELResourceMetrics", func() {
	Description("OTEL resource metrics container")
	Attribute("resource", OTELResource, "Resource information")
	Attribute("scopeMetrics", ArrayOf(OTELScopeMetrics), "Array of scope metrics")
})

OTEL resource metrics

var OTELScope = Type("OTELScope", func() {
	Description("OTEL instrumentation scope")
	Attribute("name", String, "Scope name")
	Attribute("version", String, "Scope version")
})

OTEL scope

var OTELScopeLog = Type("OTELScopeLog", func() {
	Description("OTEL scope logs container")
	Attribute("scope", OTELScope, "Instrumentation scope information")
	Attribute("logRecords", ArrayOf(OTELLogRecord), "Array of log records")
})

OTEL scope logs

var OTELScopeMetrics = Type("OTELScopeMetrics", func() {
	Description("OTEL scope metrics container")
	Attribute("scope", OTELScope, "Instrumentation scope information")
	Attribute("metrics", ArrayOf(OTELMetric), "Array of metrics")
})

OTEL scope metrics

var OTELSum = Type("OTELSum", func() {
	Description("OTEL sum metric")
	Attribute("aggregationTemporality", Any, "Aggregation temporality (number or enum string)")
	Attribute("isMonotonic", Boolean, "Whether the sum is monotonic")
	Attribute("dataPoints", ArrayOf(OTELNumberDataPoint), "Data points")
})

OTEL sum metric.

aggregationTemporality is Any because OTLP/JSON producers emit either the numeric enum (1, 2) or the string form ("AGGREGATION_TEMPORALITY_DELTA").

var ServerNameOverride = Type("ServerNameOverride", func() {
	Description("User-defined display name for a hooks server")
	Required("id", "raw_server_name", "display_name")
	Attribute("id", String, "Override ID")
	Attribute("raw_server_name", String, "Original server name from hooks")
	Attribute("display_name", String, "User-friendly display name")
})

Server name override types