Skip to content

Context

context

ContextHook — one-shot project context dump.

Protocol hook that calls build_context and returns the complete project context as HookResult metadata. Registered as ast:context via axm.hooks entry point.

ContextHook dataclass

Run one-shot project context dump.

Reads path from params (or working_dir from context). Supports slim parameter (bool) to limit depth to 0 for a compact output. Workspace-aware: if path is a uv workspace root, returns workspace-level context. The result is injected into session context via inject_result.

Source code in packages/axm-ast/src/axm_ast/hooks/context.py 
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
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
@dataclass
class ContextHook:
    """Run one-shot project context dump.

    Reads ``path`` from *params* (or ``working_dir`` from context).
    Supports ``slim`` parameter (bool) to limit depth to 0 for a compact output.
    Workspace-aware: if path is a uv workspace root, returns workspace-level context.
    The result is injected into session context via ``inject_result``.
    """

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

        Args:
            context: Session context dictionary (must contain ``working_dir``).
            **params: Optional ``path`` (overrides ``working_dir``).
                Optional ``slim`` (bool, default False) to limit output depth.

        Returns:
            HookResult with ``project_context`` dict in metadata on success.
        """
        path = params.get("path") or context.get("working_dir", ".")
        working_dir = Path(path).resolve()

        if not working_dir.is_dir():
            return HookResult.fail(f"working_dir not a directory: {working_dir}")

        slim = bool(params.get("slim", False))
        depth = 0 if slim else None

        try:
            # Lazy imports
            global \
                build_context, \
                format_context_json, \
                detect_workspace, \
                build_workspace_context
            if build_context is None:
                from axm_ast.core.context import build_context as _bc
                from axm_ast.core.context import format_context_json as _fcj
                from axm_ast.core.workspace import build_workspace_context as _bwc
                from axm_ast.core.workspace import detect_workspace as _dw

                build_context = _bc
                format_context_json = _fcj
                detect_workspace = _dw
                build_workspace_context = _bwc

            ws = detect_workspace(working_dir)
            if ws is not None:
                ctx = build_workspace_context(working_dir)
                return HookResult.ok(project_context=ctx)

            ctx = build_context(working_dir)
            formatted = format_context_json(ctx, depth=depth)

            return HookResult.ok(project_context=formatted)
        except Exception as exc:  # noqa: BLE001
            return HookResult.fail(f"Context hook failed: {exc}")
execute(context, **params)

Execute the hook action.

Parameters:

Name Type Description Default
context dict[str, Any]

Session context dictionary (must contain working_dir).

 required
**params Any

Optional path (overrides working_dir). Optional slim (bool, default False) to limit output depth.

 {}

Returns:

Type Description
HookResult

HookResult with project_context dict in metadata on success.
Source code in packages/axm-ast/src/axm_ast/hooks/context.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
def execute(self, context: dict[str, Any], **params: Any) -> HookResult:
    """Execute the hook action.

    Args:
        context: Session context dictionary (must contain ``working_dir``).
        **params: Optional ``path`` (overrides ``working_dir``).
            Optional ``slim`` (bool, default False) to limit output depth.

    Returns:
        HookResult with ``project_context`` dict in metadata on success.
    """
    path = params.get("path") or context.get("working_dir", ".")
    working_dir = Path(path).resolve()

    if not working_dir.is_dir():
        return HookResult.fail(f"working_dir not a directory: {working_dir}")

    slim = bool(params.get("slim", False))
    depth = 0 if slim else None

    try:
        # Lazy imports
        global \
            build_context, \
            format_context_json, \
            detect_workspace, \
            build_workspace_context
        if build_context is None:
            from axm_ast.core.context import build_context as _bc
            from axm_ast.core.context import format_context_json as _fcj
            from axm_ast.core.workspace import build_workspace_context as _bwc
            from axm_ast.core.workspace import detect_workspace as _dw

            build_context = _bc
            format_context_json = _fcj
            detect_workspace = _dw
            build_workspace_context = _bwc

        ws = detect_workspace(working_dir)
        if ws is not None:
            ctx = build_workspace_context(working_dir)
            return HookResult.ok(project_context=ctx)

        ctx = build_context(working_dir)
        formatted = format_context_json(ctx, depth=depth)

        return HookResult.ok(project_context=formatted)
    except Exception as exc:  # noqa: BLE001
        return HookResult.fail(f"Context hook failed: {exc}")