hook

Documentation

Overview

Package hook implements the Claude Code PreToolUse hook engine in the shared substrate. Each cli-guard consumer (coily, agent-guard,

Index

• func CheckBinaryPath(token string, allowed []string, lookup LookPath, source string) string
• func LeadingToken(seg string) string
• func SplitSegments(cmd string) []string
• func StripEnvPrefix(seg string) string
• type Decision
  • func PreToolUse(payload Payload, source string, rules []IntegrityRule, routes []Route, ...) Decision
• type IntegrityRule
• type LookPath
• type Payload
  • func ReadPayload(r io.Reader) Payload
• type Route

Functions

func CheckBinaryPath

func CheckBinaryPath(token string, allowed []string, lookup LookPath, source string) string

CheckBinaryPath resolves token via lookup and returns a non-empty hijack-warning string when the resolved path is outside allowed.

func LeadingToken

func LeadingToken(seg string) string

LeadingToken returns the first whitespace-delimited token of seg. "gh issue view" -> "gh", "" -> "".

func SplitSegments

func SplitSegments(cmd string) []string

SplitSegments breaks a bash command into the leading-token segments the engine classifies. Splits on $( ) || && | ; & boundaries.

func StripEnvPrefix

func StripEnvPrefix(seg string) string

StripEnvPrefix peels leading `env VAR=val ...` and `sudo` tokens so `env FOO=bar gh issue view` classifies the same as bare

Types

type Decision

type Decision struct {
	Block   bool
	Message string
}

Decision is what PreToolUse returns. Block=true means the caller should emit Message to stderr and exit with the host's hook-block

func PreToolUse

func PreToolUse(payload Payload, source string, rules []IntegrityRule, routes []Route, lookup LookPath) Decision

PreToolUse evaluates a payload against integrity rules, routes, and the engine-level arbitrary-code-execution deny. Returns

type IntegrityRule

type IntegrityRule struct {
	Binary       string
	AllowedPaths []string
}

IntegrityRule names a binary and the canonical absolute paths it is allowed to resolve to. A bare invocation of Binary that

type LookPath

type LookPath func(name string) (string, error)

LookPath mirrors exec.LookPath. Injected for tests.

type Payload

type Payload struct {
	ToolName  string                 `json:"tool_name"`
	ToolInput map[string]interface{} `json:"tool_input"`
	CWD       string                 `json:"cwd"`
}

Payload is the subset of Claude Code's PreToolUse hook payload the engine consumes. Other fields are ignored.

func ReadPayload

func ReadPayload(r io.Reader) Payload

ReadPayload decodes a PreToolUse payload from r. Empty stream or unparseable JSON returns an empty Payload (not an error); the engine

type Route

type Route struct {
	// Token is the bare leading-token to match, e.g. "gh", "brew".
	Token string

	// Hint is the human-readable recovery message. The engine
	// prefixes "<source> hook: blocked bare `<token>`. Recovery: "
	Hint string

	// Extra, when non-nil, is consulted for token-specific suffixes
	// after a match. Receives the matched segment so the consumer
	Extra func(segment string) string
}

Route maps a bare leading-token in argv to a recovery hint string the consumer wants surfaced when the harness denies that token.