[Feature Request]: Expose current callback hook metadata in Context

[kaligautier]

🔴 Required Information

Is your feature request related to a specific problem?

Context exposes useful execution metadata such as agent_name, node,
node_path, run_id, and function_call_id, but it does not expose which
lifecycle hook is currently being executed.

This makes reusable cross-cutting code harder to implement. A shared security,
audit, or telemetry component invoked from several plugin and agent callbacks
must receive a manually maintained string or enum from every callback in order
to distinguish before_agent, before_model, after_tool, and other stages.

The existing fields cannot be used as a reliable substitute:

• agent_name identifies the active agent, not the callback hook.
• node and node_path identify the workflow node.
• function_call_id identifies a tool call, but not the lifecycle callback.
• Introspecting __name__ is unreliable for decorators, partials, callable
  objects, callback lists, and plugin methods.

This is especially relevant now that callback fields support callback lists
(#5583), because generic wrappers may run from several hook families.

Describe the Solution You'd Like

Expose stable, read-only callback invocation metadata while a callback or
plugin hook is running. At minimum, the context should expose the lifecycle
hook kind. Optionally, it could also expose the owner and callable identity.

For example:

class CallbackHook(StrEnum):
    BEFORE_AGENT = "before_agent"
    AFTER_AGENT = "after_agent"
    BEFORE_MODEL = "before_model"
    AFTER_MODEL = "after_model"
    BEFORE_TOOL = "before_tool"
    AFTER_TOOL = "after_tool"
    ON_MODEL_ERROR = "on_model_error"
    ON_TOOL_ERROR = "on_tool_error"


@dataclass(frozen=True)
class CallbackInvocationInfo:
    hook: CallbackHook
    owner: Literal["plugin", "agent", "model", "tool"]
    callback_name: str | None = None


context.callback_info  # CallbackInvocationInfo | None

The exact API is open for discussion. A stable hook value alone would solve
the primary use case; callback_name can remain optional because not every
callable has a meaningful name.

The metadata should describe the callback that is currently executing. It
should not describe a future Agent-level callback while a Plugin-level hook is
running, and it should not alter the documented plugin/callback execution
order.

Impact on your work

This would make shared safety-policy, audit, and telemetry services easier to
reuse without manually propagating lifecycle-stage strings through every
callback adapter. It would also reduce the risk of recording or applying the
wrong policy stage after callbacks are reordered or composed.

There is no hard delivery deadline.

Willingness to contribute

No current commitment, but I can help validate the proposed behavior and test
cases.

---

🟡 Recommended Information

Describe Alternatives You've Considered

1. Pass a hook enum explicitly from every callback to shared code. This works,
   but duplicates framework metadata and can drift from the actual hook.
2. Infer the stage from agent_name, node, or function_call_id. These fields
   identify other execution concepts and are ambiguous.
3. Inspect the Python call stack or callable __name__. This is brittle with
   decorators, callback lists, partials, callable objects, and plugin methods.
4. Create one dedicated service method per callback hook. This avoids the
   ambiguity but adds repetitive adapters for cross-cutting concerns.

Proposed API / Implementation

Set callback metadata immediately before invoking each plugin or object-level
callback, and restore or clear it afterwards. If mutating the shared Context
would be unsafe for nested execution, an immutable callback-scoped context view
or an additional callback invocation argument would provide the same contract.

Tests should cover:

• Plugin-level and object-level hooks.
• Callback lists and short-circuiting.
• Nested agent/workflow execution.
• Async callbacks and concurrent invocations.
• Decorated functions, partials, and callable objects.

Additional Context

Related but distinct issues:

• Support list of callbacks for agent lifecycle hooks (before_agent_callback, after_agent_callback, etc.) #5583 added callback-list composition.
• Are node-level callbacks / plugin hooks planned for graph Workflow? #6779 asks for node-level Workflow hooks. This request is only about exposing
  the identity of an already executing callback/plugin hook.

[sanketpatil06]

Hi @kaligautier, Thank you for your feature request. It is currently under review, and we will let you know if we need any further information. We appreciate your understanding.