Documentation
¶
Overview ¶
Package safety is the runtime's canonical tool-call safety taxonomy. It attaches a Label to every tool call before any approval decision is made; the (safety mode × label) table in pkg/runtime/toolexec is what actually gates the call.
The package is a pure classifier: no I/O beyond the embedded pattern taxonomy, no verdicts, no side effects. Classification failures degrade to ClassUnknown — a labeller must never block a call.
Index ¶
Constants ¶
const ( MetaSafetyLabel = "safety_label" MetaBlastRadius = "blast_radius" MetaCategory = "category" MetaReason = "reason" )
Metadata keys carried on tool-call confirmation events. Renderers key badges and explanations off these; hook authors can match the same names.
const ( ShellToolName = "shell" BackgroundJobToolName = "run_background_job" )
Canonical names of the builtin tools that execute the shell command carried in their cmd argument. Duplicated here as string literals so pkg/safety does not depend on pkg/tools/builtin; the names are part of the user-facing wire protocol and a rename is caught by tests in both packages.
Variables ¶
This section is empty.
Functions ¶
func CommandArg ¶
CommandArg extracts the shell command string from tool-call arguments with the same precedence as the shell and background-job handlers: a non-blank canonical "cmd" wins, otherwise the "command" alias some models emit. Classifying anything else would label a command the handler does not run.
func IsCommandTool ¶ added in v1.133.0
IsCommandTool reports whether toolName runs the shell command in its cmd argument, and so must be classified by command text rather than by annotation hints.
Types ¶
type Class ¶
type Class string
Class is the three-value safety taxonomy every tool call maps onto.
const ( // ClassSafe: positively recognised as read-only / side-effect free // (a safe-list shell command or a ReadOnlyHint annotation). ClassSafe Class = "safe" // ClassDestructive: positively recognised as destructive (a // destructive-list shell command or a DestructiveHint annotation). ClassDestructive Class = "destructive" // ClassUnknown: everything the classifier has no positive // knowledge about. ClassUnknown Class = "unknown" )
type Label ¶
type Label struct {
Class Class
Origin Origin
// BlastRadius refines Class for display: safe | low | medium |
// high | unknown. Empty when the classifier had nothing to say.
BlastRadius string
// Category is the taxonomy category of the matched pattern
// (e.g. "fs-delete", "git-read"). Empty when no pattern matched.
Category string
// Reason is a human-readable explanation of the classification.
Reason string
}
Label is the safety sticker attached to a tool call.
func ClassifyCommand ¶
ClassifyCommand classifies a shell command against the embedded taxonomy of destructive and safe patterns.
- A destructive pattern matching anywhere in the command wins (worst blast radius across matches).
- Otherwise a safe pattern must match the WHOLE command; compound shell (a && b, a; b, a | b) never matches the safe list so `ls && rm -rf ~` doesn't inherit `ls`'s safe verdict.
- Everything else — including an empty command or a taxonomy load failure — is ClassUnknown. A classifier failure must degrade, never block: gating is the safety mode's job.
func LabelForHints ¶
LabelForHints maps MCP annotation hints onto a label. DestructiveHint wins over ReadOnlyHint; neither yields ClassUnknown.
func LabelToolCall ¶
LabelToolCall labels a tool call for the safety-mode table. Command tools (see IsCommandTool) are classified by command text; every other tool is labelled from its MCP annotation hints.
func (Label) Metadata ¶
Metadata renders the label as confirmation-event metadata. Empty fields are omitted so events stay lean, and the reason is only included for positive classifications (safe / destructive) — the unknown class carries boilerplate that must not clobber a more specific reason contributed by a hook.
Source Files