Skip to content

hooks

code_context_agent.agent.hooks

Hook providers for agent guidance and quality control.

This module provides HookProvider implementations that integrate with the Strands hook system for contextual guidance during agent execution.

Uses stable strands.agent.hooks API (not experimental steering).

FullModeToolError 

FullModeToolError(tool_name, error_message)

Bases: RuntimeError

Raised by FailFastHook when a critical tool returns an error in full mode.

Source code in src/code_context_agent/agent/hooks.py 
27
28
29
def __init__(self, tool_name: str, error_message: str) -> None:  # noqa: D107
    self.tool_name = tool_name
    super().__init__(f"Tool '{tool_name}' failed: {error_message}")

OutputQualityHook

Bases: HookProvider

Hook for output quality enforcement.

Checks tool results for size limit violations and logs warnings when outputs are unusually large.

register_hooks 

register_hooks(registry, **kwargs)

Register output quality callbacks.

Source code in src/code_context_agent/agent/hooks.py 
39
40
41
def register_hooks(self, registry: HookRegistry, **kwargs: Any) -> None:
    """Register output quality callbacks."""
    registry.add_callback(AfterToolCallEvent, self._check_output_quality)

ToolEfficiencyHook

Bases: HookProvider

Hook for tool usage optimization.

Warns when shell is used for tasks that have dedicated tools.

register_hooks 

register_hooks(registry, **kwargs)

Register tool efficiency callbacks.

Source code in src/code_context_agent/agent/hooks.py 
66
67
68
def register_hooks(self, registry: HookRegistry, **kwargs: Any) -> None:
    """Register tool efficiency callbacks."""
    registry.add_callback(BeforeToolCallEvent, self._check_tool_efficiency)

FailFastHook

Bases: HookProvider

Hook that raises on tool errors in --full mode.

In full mode, most tool failures should halt analysis immediately rather than silently degrading. Exempt tools (search, shutdown, MCP) are allowed to fail without halting.

register_hooks 

register_hooks(registry, **kwargs)

Register fail-fast callback.

Source code in src/code_context_agent/agent/hooks.py 
109
110
111
def register_hooks(self, registry: HookRegistry, **kwargs: Any) -> None:
    """Register fail-fast callback."""
    registry.add_callback(AfterToolCallEvent, self._check_for_error)

create_all_hooks 

create_all_hooks(*, full_mode=False)

Create all hook providers for agent guidance.

Parameters:

Name Type Description Default
full_mode bool

If True, include FailFastHook for strict error handling.

 False

Returns:

Type Description
list[HookProvider]

List of HookProvider instances.
Source code in src/code_context_agent/agent/hooks.py 
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
def create_all_hooks(*, full_mode: bool = False) -> list[HookProvider]:
    """Create all hook providers for agent guidance.

    Args:
        full_mode: If True, include FailFastHook for strict error handling.

    Returns:
        List of HookProvider instances.
    """
    hooks: list[HookProvider] = [
        OutputQualityHook(),
        ToolEfficiencyHook(),
    ]
    if full_mode:
        hooks.append(FailFastHook())
    return hooks