SuperPi.Extension behaviour (super_pi v0.1.0)

Unified 12-Hook Extension Pipeline behaviour (09 - Data Flows and Extension Injection Points.md).

Every callback is optional; modules that use SuperPi.Extension inherit pass-through default implementations and can override only the hooks they need.

The 12 Canonical Extension Hooks

on_input/2 — Intercepts raw user text before turn creation (:continue, {:transform, text, media}, :handled).
before_agent_start/2 — Mutates initial system prompt sections and active tool definitions before the run starts.
before_compact/2 — Overrides or customizes context compaction (:default, {:compacted, summary, data}, :cancel).
before_request/2 — Inspects/filters derived context messages in-memory right before provider serialization.
before_provider_request/2 — Inspects/mutates the raw provider HTTP/JSON payload or aborts the call.
after_response/2 — Inspects the completed assistant response and token usage before tool dispatch.
before_tool/3 — Permission gate and input validator before a tool executes (:allow, {:block, reason}, {:mutate_input, map}).
wrap_tool/4 — Higher-order middleware around tool execution (next.(args)).
after_tool/4 — Post-processes 3-channel tool output (output, structured_output, details) before recording pi.event.
after_tools/3 — Runs after a parallel tool batch settles (:continue, {:steer, msg}, {:handoff, agent}).
on_yield/3 — Intercepts child task or external yield waits.
after_run/2 — Verification and continuation gate when the assistant stops calling tools (:accept or {:continue, follow_up_prompt}).

Summary

Types

context()

Callbacks

after_response(assistant_msg, context)

after_run(run_summary, context)

after_tool(tool_name, args, result, context)

after_tools(batch_results, context)

before_agent_start(agent_config, context)

before_compact(compaction_req, context)

before_provider_request(provider_payload, context)

before_request(derived_context, context)

before_tool(tool_name, args, context)

on_input(input, context)

on_yield(yield_info, context)

wrap_tool(tool_name, args, next, context)

Functions

run_after_response(extensions, msg, ctx)

run_after_run(extensions, summary, ctx)

run_after_tool(extensions, tool_name, args, result, ctx)

run_after_tools(extensions, results, ctx)

run_before_agent_start(extensions, agent_cfg, ctx)

run_before_compact(extensions, req, ctx)

run_before_provider_request(extensions, payload, ctx)

run_before_request(extensions, derived, ctx)

run_before_tool(extensions, tool_name, args, ctx)

run_on_input(extensions, input, ctx)

run_wrap_tool(extensions, tool_name, args, core_exec_fun, ctx)

Types

context()

@type context() :: map()

Callbacks

after_response(assistant_msg, context)

(optional)

@callback after_response(assistant_msg :: map(), context()) :: {:ok, map()}

after_run(run_summary, context)

(optional)

@callback after_run(run_summary :: map(), context()) :: :accept | {:continue, String.t()}

after_tool(tool_name, args, result, context)

(optional)

@callback after_tool(tool_name :: String.t(), args :: map(), result :: map(), context()) ::
  {:ok, map()}

after_tools(batch_results, context)

(optional)

@callback after_tools(batch_results :: [map()], context()) ::
  :continue | {:steer, String.t()} | {:handoff, map()} | :terminate

before_agent_start(agent_config, context)

(optional)

@callback before_agent_start(agent_config :: map(), context()) :: {:ok, map()}

before_compact(compaction_req, context)

(optional)

@callback before_compact(compaction_req :: map(), context()) ::
  :default | {:compacted, String.t(), map()} | :cancel

before_provider_request(provider_payload, context)

(optional)

@callback before_provider_request(provider_payload :: map(), context()) ::
  {:ok, map()} | {:abort, term()}

before_request(derived_context, context)

(optional)

@callback before_request(derived_context :: map(), context()) :: {:ok, map()}

before_tool(tool_name, args, context)

(optional)

@callback before_tool(tool_name :: String.t(), args :: map(), context()) ::
  :allow | {:block, String.t()} | {:mutate_input, map()} | {:overwrite, map()}

on_input(input, context)

(optional)

@callback on_input(input :: String.t(), context()) ::
  :continue | {:transform, String.t(), list()} | :handled

on_yield(yield_info, context)

(optional)

@callback on_yield(yield_info :: map(), context()) :: :ok

wrap_tool(tool_name, args, next, context)

(optional)

@callback wrap_tool(
  tool_name :: String.t(),
  args :: map(),
  next :: (map() -> map()),
  context()
) :: map()