Skip to content

Index

hooks

Hook base types for AXM lifecycle hooks.

Provides :class:HookResult and :class:HookAction, the shared contracts used by all hook implementations across the ecosystem.

HookAction

Bases: Protocol

Protocol for hook implementations.

All hook actions receive a context dict with session info: - session_id: str - protocol_name: str - phase_name: str - task_name: str | None - working_dir: str | None - artifacts_path: str | None

Source code in packages/axm/src/axm/hooks/base.py
Python
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
@runtime_checkable
class HookAction(Protocol):
    """Protocol for hook implementations.

    All hook actions receive a context dict with session info:
    - session_id: str
    - protocol_name: str
    - phase_name: str
    - task_name: str | None
    - working_dir: str | None
    - artifacts_path: str | None
    """

    def execute(self, context: dict[str, Any], **params: Any) -> HookResult:
        """Execute the hook action.

        Args:
            context: Session context dictionary
            **params: Hook-specific parameters

        Returns:
            HookResult indicating success/failure with metadata
        """
        ...
execute(context, **params)

Execute the hook action.

Parameters:

Name Type Description Default
context dict[str, Any]

Session context dictionary

 required
**params Any

Hook-specific parameters

 {}

Returns:

Type Description
HookResult

HookResult indicating success/failure with metadata
Source code in packages/axm/src/axm/hooks/base.py
Python
73
74
75
76
77
78
79
80
81
82
83
def execute(self, context: dict[str, Any], **params: Any) -> HookResult:
    """Execute the hook action.

    Args:
        context: Session context dictionary
        **params: Hook-specific parameters

    Returns:
        HookResult indicating success/failure with metadata
    """
    ...

HookResult dataclass

Result of a hook execution.

Attributes:

Name Type Description
success bool

Whether the hook succeeded
error str | None

Error message if failed
metadata dict[str, Any]

Optional execution metadata
text str | None

Pre-rendered text representation of the result
Source code in packages/axm/src/axm/hooks/base.py
Python
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
@dataclass(frozen=True)
class HookResult:
    """Result of a hook execution.

    Attributes:
        success: Whether the hook succeeded
        error: Error message if failed
        metadata: Optional execution metadata
        text: Pre-rendered text representation of the result
    """

    success: bool
    error: str | None = None
    metadata: dict[str, Any] = field(default_factory=dict)
    text: str | None = None

    @classmethod
    def ok(cls, *, text: str | None = None, **metadata: Any) -> HookResult:
        """Create a successful result.

        Args:
            text: Pre-rendered text representation of the result.
            **metadata: Arbitrary key-value pairs stored in metadata.
        """
        return cls(success=True, text=text, metadata=metadata)

    @classmethod
    def fail(
        cls, error: str, *, text: str | None = None, **metadata: Any
    ) -> HookResult:
        """Create a failed result.

        Args:
            error: Human-readable error message.
            text: Pre-rendered text representation of the result.
            **metadata: Arbitrary key-value pairs stored in metadata.
        """
        return cls(success=False, error=error, text=text, metadata=metadata)

    @classmethod
    def skip(cls, reason: str = "condition not met") -> HookResult:
        """Create a skipped result (success, hook intentionally not run)."""
        return cls(success=True, metadata={"skipped": True, "reason": reason})
fail(error, *, text=None, **metadata) classmethod

Create a failed result.

Parameters:

Name Type Description Default
error str

Human-readable error message.

 required
text str | None

Pre-rendered text representation of the result.

 None
**metadata Any

Arbitrary key-value pairs stored in metadata.

 {}
Source code in packages/axm/src/axm/hooks/base.py
Python
41
42
43
44
45
46
47
48
49
50
51
52
@classmethod
def fail(
    cls, error: str, *, text: str | None = None, **metadata: Any
) -> HookResult:
    """Create a failed result.

    Args:
        error: Human-readable error message.
        text: Pre-rendered text representation of the result.
        **metadata: Arbitrary key-value pairs stored in metadata.
    """
    return cls(success=False, error=error, text=text, metadata=metadata)
ok(*, text=None, **metadata) classmethod

Create a successful result.

Parameters:

Name Type Description Default
text str | None

Pre-rendered text representation of the result.

 None
**metadata Any

Arbitrary key-value pairs stored in metadata.

 {}
Source code in packages/axm/src/axm/hooks/base.py
Python
31
32
33
34
35
36
37
38
39
@classmethod
def ok(cls, *, text: str | None = None, **metadata: Any) -> HookResult:
    """Create a successful result.

    Args:
        text: Pre-rendered text representation of the result.
        **metadata: Arbitrary key-value pairs stored in metadata.
    """
    return cls(success=True, text=text, metadata=metadata)
skip(reason='condition not met') classmethod

Create a skipped result (success, hook intentionally not run).

Source code in packages/axm/src/axm/hooks/base.py
Python
54
55
56
57
@classmethod
def skip(cls, reason: str = "condition not met") -> HookResult:
    """Create a skipped result (success, hook intentionally not run)."""
    return cls(success=True, metadata={"skipped": True, "reason": reason})