README
¶
pkg/types
Shared type definitions used across packages to avoid circular imports.
Files
| File | Role |
|---|---|
types.go |
All shared types, constants, and the JSONL scanner factory |
Key Types
HookInput
Union type for all Claude Code hook events. A single struct carries fields for every hook type — unused fields are zero-valued. This is intentional: the number of hook types is small and their fields are largely orthogonal, so splitting into separate types would add complexity without benefit.
Always-present fields: SessionID (validated by ReadHookInput). TranscriptPath is present for session hooks but not validated at this level — discovery.ReadHookInputFrom adds that validation.
Hook-specific fields:
UserPromptSubmit:PromptPreToolUse/PostToolUse:ToolName,ToolInput,ToolUseID,ToolResponseSessionStart/SessionEnd:Reason
HookResponse / PreToolUseResponse
Response types written to stdout for Claude Code to consume. PreToolUseResponse includes HookSpecificOutput with permission decisions (allow/deny with instructions).
InboxEvent
Used for inter-process communication between the sync stop command and the running daemon. Serialized as JSONL in the inbox file.
ValidateSessionID(id)
Validates that a session ID contains only safe characters (alphanumeric, hyphens, underscores) using the sessionIDPattern regex. Called by ReadHookInput to reject malformed session IDs before they reach downstream code.
NewJSONLScanner(reader)
Factory that creates a bufio.Scanner with a 10MB buffer (MaxJSONLLineSize). Transcript lines can be very large (thinking blocks, tool results), so the default 64KB buffer is insufficient.
How to Extend
Adding a field to HookInput: Add the field with json:",omitempty". No need to update ReadHookInput() — json.Unmarshal handles new fields automatically. If the field requires validation, add it to the validation block in ReadHookInput().
Adding a new shared type: Add it here only if it's needed by 2+ packages that would otherwise create a circular import. Package-specific types belong in their own package.
Invariants
HookInput.SessionIDis validated as non-empty and safe (alphanumeric, hyphens, underscores only) inReadHookInput()— all downstream code can assume it's set and safe for use in file paths.ReadHookInput()uses boundedio.ReadAll(limited toMaxJSONLLineSize) to prevent memory exhaustion from oversized input.MaxJSONLLineSize(10MB) must accommodate the largest possible transcript line. Changing this affects every JSONL reader in the codebase.NewJSONLScannermust be used everywhere JSONL files are read — never create a barebufio.Scannerfor transcript files.
Dependencies
Uses: standard library only
Used by: nearly every package (cmd/, pkg/daemon/, pkg/discovery/, pkg/sync/)
Documentation
¶
Index ¶
Constants ¶
const MaxJSONLLineSize = 10 * 1024 * 1024 // 10MB
MaxJSONLLineSize is the maximum size for a single JSONL line Default bufio.Scanner buffer is 64KB, but transcript lines with thinking blocks and tool results can exceed 1MB
Variables ¶
This section is empty.
Functions ¶
func NewJSONLScanner ¶
NewJSONLScanner creates a bufio.Scanner configured for large JSONL files with a 10MB buffer to handle long transcript lines
func ValidateSessionID ¶ added in v0.15.0
ValidateSessionID checks that a session ID contains only safe characters.
Types ¶
type HookInput ¶
type HookInput struct {
SessionID string `json:"session_id"`
TranscriptPath string `json:"transcript_path"`
CWD string `json:"cwd"`
PermissionMode string `json:"permission_mode"`
HookEventName string `json:"hook_event_name"`
Reason string `json:"reason"`
ParentPID int `json:"parent_pid,omitempty"` // Claude Code process ID (set by confab, not Claude Code)
// UserPromptSubmit-specific fields
Prompt string `json:"prompt,omitempty"`
// PreToolUse/PostToolUse-specific fields
ToolName string `json:"tool_name,omitempty"`
ToolInput map[string]any `json:"tool_input,omitempty"`
ToolUseID string `json:"tool_use_id,omitempty"`
ToolResponse map[string]any `json:"tool_response,omitempty"` // PostToolUse only
}
HookInput represents hook data from Claude Code.
This is a union type containing fields from all hook types (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, etc.). JSON unmarshaling handles missing fields gracefully. This approach is pragmatic for a small number of hooks with mostly orthogonal fields. Consider splitting into separate types if hooks start having conflicting field semantics or the number of hook types grows significantly.
type HookResponse ¶
type HookResponse struct {
Continue bool `json:"continue"`
StopReason string `json:"stopReason"`
SuppressOutput bool `json:"suppressOutput"`
SystemMessage string `json:"systemMessage,omitempty"`
}
HookResponse is the JSON response sent back to Claude Code
type InboxEvent ¶
type InboxEvent struct {
Type string `json:"type"` // Event type: "session_end"
Timestamp time.Time `json:"timestamp"` // When the event was written
HookInput *HookInput `json:"hook_input,omitempty"` // Full hook payload for session events
}
InboxEvent represents an event written to the daemon's inbox file. The inbox is a JSONL file where each line is an event.
type PreToolUseOutput ¶
type PreToolUseOutput struct {
HookEventName string `json:"hookEventName"`
PermissionDecision string `json:"permissionDecision,omitempty"` // "allow", "deny", or "ask"
PermissionDecisionReason string `json:"permissionDecisionReason,omitempty"`
UpdatedInput map[string]any `json:"updatedInput,omitempty"`
}
PreToolUseOutput contains PreToolUse-specific decision fields
type PreToolUseResponse ¶
type PreToolUseResponse struct {
HookSpecificOutput *PreToolUseOutput `json:"hookSpecificOutput,omitempty"`
}
PreToolUseResponse is the JSON response for PreToolUse hooks
Source Files