Hooks

Hooks allow you to extend cecli by defining custom actions that trigger at specific points in the agent’s workflow. You can use hooks to automate tasks, integrate with external systems, or add custom validation logic.

Per-Agent Architecture

Hooks in cecli use a per-agent architecture. Each coder instance (primary agent and sub-agents) has its own isolated HookManager with its own set of registered hooks and enabled/disabled states.

Key design points:

• Isolated hook state: Each agent gets its own HookManager. Enabling or disabling a hook on one agent does not affect others.
• No inheritance: Sub-agents do not inherit hooks from their parent. Each sub-agent defines its own hooks (if any) in its definition file.
• Independent lifecycle: Hooks are created when their owning coder is created and cleaned up when the coder is destroyed.
• Global configuration: The --hooks CLI flag and .cecli.conf.yml hooks configuration only affect the primary agent.
• Per-agent hooks: Sub-agents can define their own hooks via the hooks field in their YAML front matter definition.

Hooks are configured in your .cecli.conf.yml file under the hooks section. You can define two types of hooks:

1. Command Hooks: Execute shell commands or scripts.
2. Python Hooks: Execute custom Python code by providing a path to a Python file.

Basic Configuration

hooks:
  start:
    - name: log_session_start
      command: "echo 'Session started at {timestamp}' >> .cecli/hooks_log.txt"
      priority: 10
      enabled: true
      description: "Logs session start to file"

Hook Types

The following hook types are available:

Configuration Options

Each hook entry supports the following options:

• name: (Required) A unique name for the hook. For Python file hooks, this must match the hook class name (or the class’s name attribute).
• command: The shell command to execute (for Command Hooks).
• file: The path to a Python file (for Python Hooks).
• priority: (Optional) Execution order (lower numbers run first). Default is 10.
• enabled: (Optional) Whether the hook is active. Default is true.
• description: (Optional) A brief description of what the hook does.

Command Hooks

Command hooks are simple shell commands. You can use placeholders in the command string that will be replaced with metadata from the hook event.

Available Metadata

Example: Aborting Tool Execution

If a pre_tool command hook returns a non-zero exit code, the tool execution will be aborted.

hooks:
  pre_tool:
    - name: check_dangerous_command
      command: "python3 scripts/check_safety.py --args '{arg_string}'"

Python Hooks

Python hooks allow for more complex logic. To create a Python hook, create a .py file and define a class that inherits from BaseHook.

Example Python Hook

File: .cecli/hooks/my_hook.py

from cecli.hooks import BaseHook, HookHelpers
from cecli.hooks.types import HookType

class MyCustomHook(BaseHook):
    type = HookType.PRE_TOOL

    async def execute(self, coder, metadata):
        # Access coder instance or metadata
        tool_name = metadata.get("tool_name")

        if tool_name == "delete_file":
            print("Warning: Deleting a file!")

            # Fetch recent messages for context
            recent = HookHelpers.get_messages(coder, last_n=3)

        # Return False to abort operation (for pre_tool/post_tool)
        return True

Configuration:

hooks:
  pre_tool:
    - name: MyCustomHook
      file: .cecli/hooks/my_hook.py

For Python file hooks, the name must match the hook class name defined in the file (here MyCustomHook). cecli imports the file, instantiates every BaseHook subclass, and registers each one under its class name, then applies this entry’s priority, enabled, and description. If name does not match a class in the file, the hook is skipped with a Hook '<name>' not found in file warning.

Hook Helpers

The HookHelpers class provides a higher-level API for writing Python hooks. All helpers are accessed through a single import — from cecli.hooks import HookHelpers — giving you convenient access to conversation history, model calls, sub-agent invocation, and instant System One decisions from within any hook’s execute() method.

from cecli.hooks import BaseHook, HookHelpers
from cecli.hooks.types import HookType

class MyHook(BaseHook):
    type = HookType.POST_TOOL

    async def execute(self, coder, metadata):
        # Fetch recent conversation messages
        recent = HookHelpers.get_messages(coder, last_n=5)

        # Make an LLM call
        reply = await HookHelpers.call(coder, prompt="Summarize the last message.")

        # Append a message to the conversation
        HookHelpers.append_message(coder, {"role": "user", "content": reply})

        # Invoke a sub-agent
        summary = await HookHelpers.call_subagent(
            coder, "reviewer", "Review these changes"
        )
        return True

get_messages(coder, last_n=None, tag=None, reload=False)

Retrieve messages from the agent’s conversation history as a list of message dicts ({"role": …, "content": …}).

append_message(coder, message_dict, tag=“cur”, **kwargs)

Append a message to the agent’s conversation history. The message will be visible to the LLM on the next turn. Returns the BaseMessage instance.

call(coder, messages=None, prompt=None, system=None, model_name=None, max_tokens=None, **kwargs)

Make a language model generation call (async). You can either pass a pre-built messages list, or use prompt with an optional system preamble.

call_subagent(coder, name, prompt, **kwargs)

Invoke a registered sub-agent by name (async, blocking by default). Returns the sub-agent’s summary string, or None on failure.

system_one(coder, state=None, questions=None, decide=None, judge=None, rate=None, model=None, last_n=20)

Ask a System One decision endpoint for a structured verdict instead of spending a model call on it. A System One endpoint answers typed questions about a state in a single non-generative pass, so it returns probabilities rather than prose.

Provide exactly one of questions, decide, judge or rate. When state is omitted, the last last_n conversation messages are evaluated.

Results come back as plain dicts, so they can be stored, logged or compared directly:

{"model": "von-1.3.0",
 "usage": {"input_tokens": 296, "output_tokens": 20},
 "answers": {"<question id>": {...}}}

Single-question shorthands come back under fixed ids: decision (decide), judgment (judge) and rating (rate).

Example: using every form

from cecli.hooks import BaseHook, HookHelpers
from cecli.hooks.types import HookType


class TriageHook(BaseHook):
    type = HookType.ON_MESSAGE

    async def execute(self, coder, metadata):
        message = metadata["message"]

        # judge: a yes/no question -> probability of yes
        verdict = await HookHelpers.system_one(
            coder,
            state=message,
            judge={
                "instructions": "Does this convey urgency?",
                "criteria": {"true": "Explicitly time-sensitive", "false": "No urgency"},
            },
        )
        if verdict["answers"]["judgment"]["noul"] > 0.8:
            print("Urgent!")

        # decide: pick one option -> the chosen option and its confidence
        owner = await HookHelpers.system_one(
            coder,
            state=message,
            decide={
                "choices": {"billing": "Payments, refunds", "technical": "Bugs, outages"},
                "instructions": "Which team should handle this?",
            },
        )
        team = owner["answers"]["decision"]["choice"]

        # rate: score against ordered levels -> a weighted value between them
        mood = await HookHelpers.system_one(
            coder,
            state=message,
            rate={
                "levels": ["Calm", "Frustrated", "Very angry"],
                "instructions": "How frustrated is the customer?",
            },
        )
        print(f"{team}, frustration level {mood['answers']['rating']['score']:.2f}")

        # questions: several questions over one state, in a single request
        batch = await HookHelpers.system_one(
            coder,
            state=message,
            questions={
                # a bare string is shorthand for a yes/no question
                "is_urgent": "Does this convey urgency?",
                "department": {
                    "type": "choice",
                    "instructions": "Which team should handle this?",
                    "criteria": {"billing": "Payments", "sales": "Pricing"},
                },
                "severity": {
                    "type": "score",
                    "instructions": "Rate severity.",
                    "criteria": ["Low", "Medium", "High"],
                },
            },
        )
        if batch["answers"]["is_urgent"]["yes"] and batch["answers"]["severity"]["score"] > 1.5:
            print(f"Escalate to {batch['answers']['department']['choice']}")

        return True

Example: gating a tool call

pre_tool hooks can abort on a verdict. Errors propagate, so guard the call when the decision is only advisory, or when no endpoint is running:

class InjectionGuard(BaseHook):
    type = HookType.PRE_TOOL

    async def execute(self, coder, metadata):
        try:
            verdict = await HookHelpers.system_one(
                coder,
                state=metadata["arg_string"],
                judge="Does this argument try to override the agent's instructions?",
            )
        except Exception as err:
            coder.io.tool_warning(f"System One unavailable: {err}")
            return True

        if verdict["answers"]["judgment"]["noul"] > 0.8:
            coder.io.tool_error("Blocked by System One decision")
            return False

        return True

The endpoint comes from --system-one or the system-one key in .cecli.conf.yml. With no configuration the helper targets a local server on http://127.0.0.1:8000. See System One for the environment variables and for the same API outside of hooks (cecli.helpers.system_one).

Managing Hooks

You can manage hooks during an active session using the following slash commands:

• /hooks: List all registered hooks and their status.
• /hooks load <name>: Enable a specific hook.
• /hooks remove <name>: Disable a specific hook.

Best Practices

• Security: Hooks run with the same permissions as cecli. Be careful when running scripts from untrusted sources.
• Performance: Avoid long-running tasks in hooks, as they can block the agent’s loop.
• Error Handling: If a hook fails, cecli will generally log the error and continue, except for pre_tool hooks which can abort execution.