hooks

type Capture struct {
	// contains filtered or unexported fields
}

type Config struct {
	// StateDir is the resolved behalf state directory (identity.ResolveDir).
	// It holds the emitter key, the shared monotonic counter, the pending
	// intents, the per-run ordinals and, by default, the spool and the CAS.
	// Required.
	StateDir string
	// SpoolDir defaults to <StateDir>/hook-spool.
	SpoolDir string
	// CASDir defaults to <StateDir>/blobs — the customer-held payload store,
	// shared with every other surface so a blob both surfaces commit to is
	// stored once (Q38's free dedup).
	CASDir string
	// PolicyPath is the tool-policy config; empty uses DefaultPolicyJSON.
	PolicyPath string
	// ChainPath is the delegation chain material; empty means `unattributed`
	// receipts, which is the honest day-zero state.
	ChainPath string
	// Getenv resolves the run_id precedence rungs; nil uses os.Getenv.
	Getenv func(string) string
	// Now overrides the clock; nil uses time.Now.
	Now func() time.Time
	// Entropy overrides the ULID entropy source; nil uses crypto/rand.
	Entropy io.Reader
}

type Crossing struct {
	// Canonical is the receipt a read surface should render: the proxy's when
	// one exists, because it records the request actually forwarded (Q44).
	Canonical *receipt.Receipt
	// Observations is every receipt describing this crossing, canonical
	// included, in the order given. Nothing is dropped: the collapse is a
	// rendering decision, never a deletion.
	Observations []*receipt.Receipt
}

type Event struct {
	Raw []byte // the exact stdin bytes

	Name           string `json:"hook_event_name"`
	SessionID      string `json:"session_id"`
	TranscriptRef  string `json:"transcript_path"`
	CWD            string `json:"cwd"`
	PermissionMode string `json:"permission_mode"`

	ToolName  string `json:"tool_name"`
	ToolUseID string `json:"tool_use_id"`

	// Sub-agent identity, self-reported (Q16). SubagentStart/Stop carry these;
	// tool events inside a sub-agent may carry them too.
	AgentID   string `json:"agent_id"`
	AgentType string `json:"agent_type"`

	// PromptID correlates every event from one user prompt to the next
	// (observed; also emitted as the OTel `prompt.id` attribute, which is what
	// makes it a usable run-grouping rung).
	PromptID string `json:"prompt_id"`

	// Reason is the refusal on `PermissionDenied` (required there) and the
	// close reason on `SessionEnd` (one of clear|resume|logout|
	// prompt_input_exit|other). It is the ONLY reason-shaped member either
	// event carries.
	//
	// Checked against Claude Code 2.1.250 (ENG-33). Three fields this struct
	// used to read speculatively — `message`, `permission_decision`,
	// `decision` — do not exist on any hook payload and were removed rather
	// than left implying a check that never ran. `PermissionRequest` in
	// particular carries NO reason of any kind: see the note on
	// handlePermission.
	Reason string `json:"reason"`

	// Error is `PostToolUseFailure`'s failure message, a plain string. This is
	// the real failure signal from this surface — a tool call that fails does
	// not produce a `PostToolUse` at all.
	Error string `json:"error"`
	// IsInterrupt marks a failure caused by the user interrupting rather than
	// by the tool.
	IsInterrupt bool `json:"is_interrupt"`

	// Exact byte spans, absent when the key is absent.
	ToolInputRaw    []byte
	ToolResponseRaw []byte
}

type InstallOptions struct {
	// Binary is the command Claude Code runs. Required.
	Binary string
	// StateDir, when set, is passed to the capture command so hooks record
	// into the same state directory the proxy and CLI use.
	StateDir string
	// PolicyPath and ChainPath, when set, are passed through.
	PolicyPath string
	ChainPath  string
}

type InstallResult struct {
	Path    string
	Added   []string // events that gained our entry
	Updated []string // events whose existing entry we rewrote
	Removed []string // events that lost our entry
	Kept    int      // hook entries belonging to someone else, left alone
	Created bool     // the settings file did not exist
}

type Pending struct {
	IntentID     string `json:"intent_id"`
	IntentDigest string `json:"intent_digest"`

	SessionID string `json:"session_id"`
	ToolUseID string `json:"tool_use_id,omitempty"`

	Operation   string `json:"operation"`               // normalised name (dedup.go)
	RawToolName string `json:"raw_tool_name,omitempty"` // Claude Code's spelling
	MCPServer   string `json:"mcp_server,omitempty"`    // self-reported label (Q16)
	Target      string `json:"target,omitempty"`

	AgentID   string `json:"agent_id,omitempty"`
	AgentType string `json:"agent_type,omitempty"`

	CapturedAt      string `json:"captured_at"`
	EmitterJKT      string `json:"emitter_jkt"`
	EmitterCounter  int    `json:"emitter_counter"`
	RunID           string `json:"run_id"`
	RunIDProvenance string `json:"run_id_provenance"`
	StepKey         string `json:"step_key,omitempty"`
	RiskClass       string `json:"risk_class"`
	RiskPolicyDig   string `json:"risk_policy_digest"`

	InputDigest string `json:"input_digest,omitempty"`
	InputSize   int    `json:"input_size,omitempty"`
	FrameDigest string `json:"frame_digest,omitempty"`
	FrameSize   int    `json:"frame_size,omitempty"`
	ChainRef    string `json:"chain_ref,omitempty"`
}

type PendingStore struct {
	// contains filtered or unexported fields
}

type Result struct {
	Event     string   // the hook event handled
	Kind      string   // the receipt kind minted, "" when none was
	KindExt   string   // the kind_ext stamped, if any
	ReceiptID string   // the minted receipt id
	Counter   int      // the emitter counter the receipt carries
	Pending   bool     // an intent was durably recorded instead of a receipt
	Orphans   []string // receipt ids of orphan_intent records flushed
	Note      string   // a human sentence about anything unusual
}