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 depth parameter (int | None) to control output granularity (0 = compact, 1 = packages, None = full). 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
Python
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
@dataclass
class ContextHook:
    """Run one-shot project context dump.

    Reads ``path`` from *params* (or ``working_dir`` from context).
    Supports ``depth`` parameter (int | None) to control output granularity
    (0 = compact, 1 = packages, None = full).
    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, object], **params: object) -> HookResult:
        """Execute the hook action.

        Args:
            context: Session context dictionary (must contain ``working_dir``).
            **params: Optional ``path`` (overrides ``working_dir``).
                Optional ``depth`` (int | None, default None) to control output
                granularity (0 = compact, 1 = packages, None = full).

        Returns:
            HookResult with ``project_context`` dict in metadata on success.
        """
        validated = _validate_context_params(context, params)
        if isinstance(validated, HookResult):
            return validated
        working_dir, depth = validated

        try:
            _ensure_context_imports()
            assert build_context is not None
            assert detect_workspace is not None
            assert build_workspace_context is not None
            assert format_context_json is not None

            ws = detect_workspace(working_dir)
            if ws is not None:
                ws_ctx = build_workspace_context(working_dir)
                return HookResult.ok(project_context=ws_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, object]

Session context dictionary (must contain working_dir).

 required
**params object

Optional path (overrides working_dir). Optional depth (int | None, default None) to control output granularity (0 = compact, 1 = packages, None = full).

 {}

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
Python
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
def execute(self, context: dict[str, object], **params: object) -> HookResult:
    """Execute the hook action.

    Args:
        context: Session context dictionary (must contain ``working_dir``).
        **params: Optional ``path`` (overrides ``working_dir``).
            Optional ``depth`` (int | None, default None) to control output
            granularity (0 = compact, 1 = packages, None = full).

    Returns:
        HookResult with ``project_context`` dict in metadata on success.
    """
    validated = _validate_context_params(context, params)
    if isinstance(validated, HookResult):
        return validated
    working_dir, depth = validated

    try:
        _ensure_context_imports()
        assert build_context is not None
        assert detect_workspace is not None
        assert build_workspace_context is not None
        assert format_context_json is not None

        ws = detect_workspace(working_dir)
        if ws is not None:
            ws_ctx = build_workspace_context(working_dir)
            return HookResult.ok(project_context=ws_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}")