Documentation
¶
Overview ¶
Package hook implements Claude Code hook endpoints (`sf hook pre`).
PreToolUse guards the Read channel — the biggest unintercepted token producer (≈1M result-tokens/week vs ≈270k lifetime for `sf code`): a full Read/cat of a big source file lands in the context window once and is then cache-read on every following turn. The hook nudges the agent toward the structural path (`sf code <file>` → `sf code <file> <Symbol>`) instead.
Modes (SOFIA_HOOK_MODE):
off — do nothing;
suggest — allow the call, attach an advisory note (additionalContext);
nudge — deny the FIRST full read of a given file per session with an
actionable reason; an identical repeated call passes (so an
agent that truly needs the body — e.g. before Edit — recovers
in one turn). Default.
strict — always deny full reads of big source files.
Fail-open by design: any parse/IO problem inside the hook results in a silent allow — the hook must never break a session.
Index ¶
Constants ¶
const ( ActionSuggest = "suggest" ActionDeny = "deny" )
Actions a decision can take. Empty action means "allow silently".
Variables ¶
This section is empty.
Functions ¶
func NewCommand ¶
NewCommand returns the hidden `sf hook` group. It is harness plumbing (wired in ~/.claude/settings.json), not a tool for humans, hence Hidden.
Types ¶
type Decision ¶
type Decision struct {
Action string // "", ActionSuggest or ActionDeny
Path string // resolved target file
Bytes int64 // its size
Reason string // text fed to the model (deny reason or advisory note)
}
Decision is the outcome of Decide for one tool call.
type Input ¶
type Input struct {
SessionID string `json:"session_id"`
CWD string `json:"cwd"`
ToolName string `json:"tool_name"`
ToolInput json.RawMessage `json:"tool_input"`
}
Input is the subset of the PreToolUse stdin payload the hook cares about.
type State ¶
type State struct {
// contains filtered or unexported fields
}
State remembers which files were already nudged in a session, so the second identical call passes. One small file per session id under <state>/hook/; entries older than two days are pruned opportunistically.
Source Files