feat: Add support for sandbox diagnostic log (#245)

* feat: Add support for sandbox diagnostic log

* fix: Normalize and prioritise sandbox violations

* fix: Code review fixes

sandbox/sandbox.go

@@ -5,6 +5,43 @@ import (
 	"os/exec"
 )
 
+// ViolationKind is PMG's normalized taxonomy for sandbox denials.
+type ViolationKind string
+
+const (
+	ViolationKindFSRead           ViolationKind = "fs_read"
+	ViolationKindFSWrite          ViolationKind = "fs_write"
+	ViolationKindFSDeleteOrRename ViolationKind = "fs_delete_or_rename"
+	ViolationKindExec             ViolationKind = "exec"
+	ViolationKindNetworkConnect   ViolationKind = "network_connect"
+	ViolationKindNetworkBind      ViolationKind = "network_bind"
+	ViolationKindGenericDeny      ViolationKind = "generic_deny"
+)
+
+// ViolationReport is a best-effort sandbox violation summary collected from a
+// sandbox implementation after command execution fails.
+type ViolationReport struct {
+	SandboxName   string
+	PolicyName    string
+	CorrelationID string
+	Violations    []Violation
+}
+
+// Violation captures one sandbox denial event.
+type Violation struct {
+	Kind       ViolationKind
+	RawKind    string
+	Target     string
+	RuleTarget string
+	Process    string
+	RawLog     string
+	RuleLabel  string
+}
+
+type violationReporter interface {
+	BestEffortViolation(err error) (*ViolationReport, error)
+}
+
 // ExecutionResult represents the result of executing a command in a sandbox.
 // It contains sandbox internal state and allows for future extension with
 // additional metadata (e.g., exit codes, resource usage, violation events).
@@ -46,6 +83,22 @@ func (r *ExecutionResult) ShouldRun() bool {
 	return !r.executed
 }
 
+// BestEffortViolation returns sandbox-specific best-effort violation details.
+// Implementations may use platform logs or other weak signals, so callers
+// should treat the result as advisory.
+func (r *ExecutionResult) BestEffortViolation(err error) (*ViolationReport, error) {
+	if r == nil || r.sandbox == nil {
+		return nil, nil
+	}
+
+	reporter, ok := r.sandbox.(violationReporter)
+	if !ok {
+		return nil, nil
+	}
+
+	return reporter.BestEffortViolation(err)
+}
+
 // Close cleans up any resources allocated by the sandbox.
 // Must be called after cmd.Run() completes.
 func (r *ExecutionResult) Close() error {