Documentation
¶
Overview ¶
Package hookapi defines the agent-neutral hook contract. Agent adapters translate each agent's native hook JSON into a HookEvent and translate the resulting Decision back; the steering core only ever sees these types.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Action ¶
type Action string
Action is the steering verdict for a hook event.
const ( ActionAllow Action = "allow" // explicitly permit the tool call ActionDeny Action = "deny" // block; Reason is shown to the model ActionAsk Action = "ask" // defer to the user (agent permitting) ActionNoop Action = "noop" // express no opinion; agent default applies )
Actions.
func ParseAction ¶
ParseAction parses an action name case-insensitively.
type Agent ¶
type Agent string
Agent identifies the AI coding agent that fired a hook.
const ( AgentClaude Agent = "claude" AgentCodex Agent = "codex" AgentCursor Agent = "cursor" AgentOpenCode Agent = "opencode" )
Supported agents.
func ParseAgent ¶
ParseAgent parses an agent name case-insensitively ("claude-code" is accepted as an alias for claude).
type Decision ¶
type Decision struct {
Action Action `json:"action,omitempty"`
// Reason is shown to the model, primarily on deny.
Reason string `json:"reason,omitempty"`
// AdditionalContext is injected into the model context (session start
// summaries, read outlines).
AdditionalContext string `json:"additional_context,omitempty"`
// UserMessage is shown to the human only.
UserMessage string `json:"user_message,omitempty"`
// UpdatedInput optionally rewrites the tool input (agent permitting).
UpdatedInput json.RawMessage `json:"updated_input,omitempty"`
}
Decision is the agent-neutral hook result. Adapters render it into each agent's native output (exit code, hookSpecificOutput, permission, ...).
func (Decision) WithContext ¶
WithContext returns a copy of d with AdditionalContext set.
func (Decision) WithUserMessage ¶
WithUserMessage returns a copy of d with UserMessage set.
type Event ¶
type Event string
Event is a normalized hook lifecycle event.
const ( EventSessionStart Event = "session-start" EventSubagentStart Event = "subagent-start" EventPreToolUse Event = "pre-tool-use" EventPostToolUse Event = "post-tool-use" EventPreCompact Event = "pre-compact" EventStop Event = "stop" )
Hook events. String values are the kebab-case CLI spelling used by `graphmaster hook <event>`.
func ParseEvent ¶
ParseEvent accepts the kebab-case, snake_case, PascalCase or camelCase spelling of an event. Agent-specific events (e.g. Cursor's afterFileEdit) must be mapped by the adapter first.
func (Event) IsToolEvent ¶
IsToolEvent reports whether the event carries a tool invocation.
type HookEvent ¶
type HookEvent struct {
Agent Agent `json:"agent"`
Event Event `json:"event"`
SessionID string `json:"session_id,omitempty"`
// AgentID identifies a subagent within the session; "" for the main agent.
AgentID string `json:"agent_id,omitempty"`
AgentType string `json:"agent_type,omitempty"` // e.g. "Explore", "Plan"
Tool Tool `json:"tool,omitempty"`
Pattern string `json:"pattern,omitempty"` // search pattern (grep)
// Paths are the target files or directories, as given by the agent
// (absolute or relative to CWD).
Paths []string `json:"paths,omitempty"`
Glob string `json:"glob,omitempty"` // glob pattern or grep file filter
Command string `json:"command,omitempty"` // shell command text
CWD string `json:"cwd,omitempty"`
ToolUseID string `json:"tool_use_id,omitempty"`
Raw json.RawMessage `json:"raw,omitempty"` // original payload, for logging/dedupe
}
HookEvent is one agent-neutral hook invocation.
func (HookEvent) IsSubagent ¶
IsSubagent reports whether the event came from a subagent.
type Tool ¶
type Tool string
Tool is the normalized category of the tool an agent is invoking.
const ( ToolGrep Tool = "grep" // content search (Claude Grep, Cursor Grep) ToolGlob Tool = "glob" // file-name search ToolRead Tool = "read" // file read ToolShell Tool = "shell" // shell command (Bash, Shell, beforeShellExecution) ToolPatch Tool = "patch" // multi-file patch (Codex apply_patch) ToolMCP Tool = "mcp" // MCP tool call ToolEdit Tool = "edit" // in-place file edit ToolWrite Tool = "write" // whole-file write ToolOther Tool = "other" // anything else )
Tool categories.
func (Tool) IsMutation ¶
IsMutation reports whether t modifies files (triggers a dirty hint).
Source Files