classifier

type ClassificationContext struct {
	Cwd        string
	IsGitRepo  bool
	RepoRoot   string
	IsWorktree bool
	// Env is an optional map of environment variable names to values used to expand
	// $VAR and ${VAR} references in Bash commands before classification. This is
	// primarily useful in tests and CI to evaluate commands that contain dynamic
	// variables (e.g. BRANCH=main "git checkout $BRANCH" → "git checkout main").
	// Variables not present in the map are left unexpanded.
	Env map[string]string
	// CIStatus is the requesting session's GitHub CI check conclusion:
	// "success"/"failure"/"pending"/"neutral"/"". "" means no PR or unknown
	// (including stale data — see ApprovalHandler's staleness guard).
	CIStatus string
	// SessionIdleMinutes is the computed idle-minutes value for the session being
	// classified. 0 (unset) means unknown/unavailable and must never accidentally
	// satisfy a MinSessionIdleMinutes > 0 condition — see ApprovalHandler's population
	// logic for how this is populated from a live instance.
	SessionIdleMinutes int
}

type ClassificationDecision int

type ClassificationResult struct {
	Decision    ClassificationDecision
	RiskLevel   RiskLevel
	Reason      string
	Alternative string
	RuleID      string
	RuleName    string
	Source      string // rule source: "seed", "user", or "claude-settings"
}

type Classifier interface {
	Classify(payload PermissionRequestPayload, ctx ClassificationContext) ClassificationResult
	BuildContext(cwd string) ClassificationContext
}

type CommandCriteria struct {
	// Programs lists the allowed primary programs. Empty means any program matches.
	// Prefix matching handles versioned interpreters (e.g., "python3" matches "python3.11").
	Programs []string
	// Subcommands lists allowed subcommand values. Empty means any (or no) subcommand matches.
	// For deep-subcommand programs (gh, aws, etc.) multi-word entries are supported ("pr view").
	Subcommands []string
	// BlockedSubcommands lists subcommands that prevent this rule from matching.
	BlockedSubcommands []string
	// RequiredFlags: at least one of the listed flags must be present in the command args.
	// Uses exact token matching (e.g., RequiredFlags: ["--hard"] matches git reset --hard only).
	RequiredFlags []string
	// RequiredFlagPrefixes: like RequiredFlags but uses prefix matching.
	// Useful when a flag accepts an optional inline value (e.g., sed -i.bak satisfies prefix "-i").
	RequiredFlagPrefixes []string
	// ForbiddenFlags: if any of these flags appear in args, the rule does not match.
	ForbiddenFlags []string
	// PythonModes restricts matching to specific Python invocation modes.
	// Valid values: "inline" (-c), "module" (-m), "version" (-V/--version), "script" (*.py).
	// Empty means no Python-mode check is performed.
	PythonModes []string
	// SafePythonImportsOnly restricts inline Python (-c) matches to commands whose
	// import statements use only known-safe stdlib modules (see safeStdlibModules).
	// When true the rule will not match if any import is outside the safelist, or if
	// the invocation is not inline. Combine with PythonModes: ["inline"].
	SafePythonImportsOnly bool
	// RedirectionPattern matches against any file paths targeted by shell redirections.
	RedirectionPattern *regexp.Regexp
}

type CommandInfo struct {
	// Program is the primary executable being invoked (first non-env-var, non-wrapper token).
	Program string
	// Subcommand is the first positional argument after the program, if it looks like a
	// subcommand (i.e., does not start with '-').
	Subcommand string
	// Category classifies Program into a high-level category (e.g., "vcs", "runtime").
	Category string
	// AllPrograms contains all distinct programs found across the full command line,
	// including across pipes, semicolons, and logical operators.
	AllPrograms []string
}

type EscalationCategory string

type ParsedCommand struct {
	// Program is the primary executable (path-stripped).
	Program string
	// Args is the list of remaining tokens.
	Args []string
	// Raw is the reconstructed "program arg1 arg2 …" string for pattern matching.
	Raw string
	// Redirections lists the targets of any shell redirections (e.g., "> file", ">> file").
	Redirections []string
	// FromCmdSubst is true when this command was extracted from inside a $(...) or `...`
	// substitution. Such commands are evaluated as argument values for the outer command,
	// not as independent top-level commands.
	FromCmdSubst bool
	// HasShellExpansionProgram is true when the program token itself is an unresolvable
	// shell expansion — either a simple variable ($VAR, ${VAR}) or a command substitution
	// ($(cmd)) that could not be resolved to a known program name by path-stripping.
	// Examples: "$SCRIPT", "$(which python)", "${CMD}".
	HasShellExpansionProgram bool
}

type PermissionRequestPayload 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"`
	ToolName       string                 `json:"tool_name"`
	ToolInput      map[string]interface{} `json:"tool_input"`
	// Source identifies which agent's hook sent this payload: "claude" or "pi".
	// Optional and backward compatible — Claude's existing curl-based hook
	// command is unmodified and simply omits it (empty string). Defaulted to
	// "claude" only at the audit/analytics recording boundary, never here.
	// See pi-support Epic 4.3 / ADR-related plan.md Story 4.3.1.
	Source string `json:"source,omitempty"`
}

type PythonInfo struct {
	// Imports contains top-level module names imported in inline Python code.
	// Only populated when -c is used (inline code), not for script files.
	Imports []string
	// IsInline is true when code was passed via the -c flag.
	IsInline bool
	// Code is the extracted Python source passed via -c, with surrounding quotes stripped.
	Code string
	// CodeWithoutComments is Code with whole-line Python comments (lines whose first
	// non-whitespace character is '#') removed. Use this for banned-pattern detection
	// so that a comment like "# open() is dangerous" does not trigger a false positive.
	CodeWithoutComments string
}

type RiskLevel int

type Rule struct {
	ID   string
	Name string
	// ToolName is an exact match on the tool name (case-insensitive). If non-empty, ToolPattern is ignored.
	ToolName string
	// ToolPattern matches against the tool name when ToolName is empty.
	ToolPattern *regexp.Regexp
	// ToolCategory matches against the structural category returned by CategorizeToolName.
	// Evaluated after ToolName/ToolPattern (those take precedence when non-empty).
	// Use one of the ToolCategory* constants. Empty string means any category matches.
	ToolCategory string
	// Criteria provides structured matching for Bash command programs, subcommands and flags.
	// When set alongside CommandPattern, both must match (AND semantics).
	Criteria *CommandCriteria
	// CommandPattern matches against tool_input["command"]. nil means any command matches.
	CommandPattern *regexp.Regexp
	// FilePattern matches against tool_input["file_path"]. nil means any file path matches.
	FilePattern *regexp.Regexp
	// RequireCIPassing, when true, only matches if ClassificationContext.CIStatus == "success".
	// ANDed with all other conditions on this rule.
	RequireCIPassing bool
	// MinSessionIdleMinutes matches only if ClassificationContext.SessionIdleMinutes >=
	// MinSessionIdleMinutes. 0 = condition not applied. ANDed with all other conditions
	// on this rule.
	MinSessionIdleMinutes int32
	Decision              ClassificationDecision
	RiskLevel             RiskLevel
	Reason                string
	Alternative           string
	// Priority determines rule evaluation order. Higher values are evaluated first.
	Priority int
	Enabled  bool
	// Source tracks how the rule was loaded: SourceSeed, SourceUser, or SourceClaudeSettings.
	Source string
}

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

type RuleSource string

type SecurityFinding struct {
	ID          string
	Name        string
	RiskLevel   RiskLevel
	Reason      string
	Alternative string
}