feat: added token delegation hooks and fixed CMF, CMF hooks, and made single functions have multiple hooks.

Signed-off-by: Teryl Taylor <terylt@ibm.com>

Author: terylt

cpex/framework/base.py

@@ -455,7 +455,7 @@ def __init__(self, hook: str, plugin_ref: PluginRef):
 
                 # Check for @hook decorator metadata
                 metadata = get_hook_metadata(method)
-                if metadata and metadata.hook_type == hook:
+                if metadata and metadata.matches(hook):
                     self._func = method
                     break
 

cpex/framework/cmf/message.py

@@ -896,12 +896,8 @@ class Message(BaseModel):
     role: Role = Field(description="Who is speaking.")
     content: list[ContentPartUnion] = Field(default_factory=list, description="List of typed content parts.")
     channel: Channel | None = Field(default=None, description="Optional output classification.")
-    extensions: Extensions | None = Field(
-        default=None,
-        description="Contextual metadata (identity, security, governance, etc.).",
-    )
 
-    def iter_views(self, hook: str | None = None) -> Iterator[MessageView]:
+    def iter_views(self, hook: str | None = None, extensions: Extensions | None = None) -> Iterator[MessageView]:
         """Decompose this message into individually addressable MessageViews.
 
         Yields one MessageView per content part. Each view provides a
@@ -938,7 +934,7 @@ def iter_views(self, hook: str | None = None) -> Iterator[MessageView]:
         """
         from cpex.framework.cmf.view import iter_views  # pylint: disable=import-outside-toplevel
 
-        return iter_views(self, hook=hook)
+        return iter_views(self, hook=hook, extensions=extensions)
 
 
 if TYPE_CHECKING:

cpex/framework/cmf/view.py

@@ -210,27 +210,31 @@ class MessageView:
         True
     """
 
-    __slots__ = ("_part", "_kind", "_message", "_hook")
+    __slots__ = ("_part", "_kind", "_message", "_extensions", "_hook")
 
     def __init__(
         self,
         part: ContentPart,
         kind: ViewKind,
         message: Message,
         hook: str | None = None,
+        extensions: Any = None,
     ) -> None:
         """Initialize a MessageView.
 
         Args:
             part: The underlying content part.
             kind: The kind of content.
-            message: The parent message (for role and extensions access).
+            message: The parent message (for role access).
             hook: The hook location where this view is being evaluated
                 (e.g., "llm_input", "tool_post_invoke"). None if unset.
+            extensions: The Extensions object, passed separately from the
+                message for capability-gated filtering.
         """
         self._part = part
         self._kind = kind
         self._message = message
+        self._extensions = extensions
         self._hook = hook
 
     # =========================================================================
@@ -631,8 +635,8 @@ def is_media(self) -> bool:
     # =========================================================================
 
     def _ext(self) -> Any:
-        """Get the message extensions, or None."""
-        return self._message.extensions
+        """Get the extensions, or None."""
+        return self._extensions
 
     # --- Base tier (no capability required) ---
 
@@ -1169,7 +1173,7 @@ def __repr__(self) -> str:
 # ---------------------------------------------------------------------------
 
 
-def iter_views(message: Message, hook: str | None = None) -> Iterator[MessageView]:
+def iter_views(message: Message, hook: str | None = None, extensions: Any = None) -> Iterator[MessageView]:
     """Iterate over a message yielding one MessageView per content part.
 
     Memory-efficient: views are yielded one at a time and hold only
@@ -1216,4 +1220,4 @@ def iter_views(message: Message, hook: str | None = None) -> Iterator[MessageVie
         if kind is None:
             logger.warning("Unknown content type %r in iter_views", part.content_type)
             raise ValueError(f"Unknown content type: {part.content_type!r}")
-        yield MessageView(part, kind, message, hook=hook)
+        yield MessageView(part, kind, message, hook=hook, extensions=extensions)

cpex/framework/decorator.py

@@ -38,7 +38,7 @@ def tool_pre_invoke(self, payload, context):
 """
 
 # Standard
-from typing import Callable, Optional, Type, TypeVar
+from typing import Callable, Optional, Sequence, Type, TypeVar, Union
 
 # Third-Party
 from pydantic import BaseModel
@@ -58,55 +58,72 @@ class HookMetadata:
     """Metadata stored on decorated hook methods.
 
     Attributes:
-        hook_type: The hook type identifier (e.g., 'tool_pre_invoke')
-        payload_type: Optional payload class for hook registration
-        result_type: Optional result class for hook registration
+        hook_types: The hook type identifiers this method handles.
+        payload_type: Optional payload class for hook registration.
+        result_type: Optional result class for hook registration.
     """
 
     def __init__(
         self,
-        hook_type: str,
+        hook_types: list[str],
         payload_type: Optional[Type[BaseModel]] = None,
         result_type: Optional[Type[BaseModel]] = None,
     ):
         """Initialize hook metadata.
 
         Args:
-            hook_type: The hook type identifier
-            payload_type: Optional payload class for registering new hooks
-            result_type: Optional result class for registering new hooks
+            hook_types: List of hook type identifiers this method handles.
+            payload_type: Optional payload class for registering new hooks.
+            result_type: Optional result class for registering new hooks.
         """
-        self.hook_type = hook_type
+        self.hook_types = hook_types
         self.payload_type = payload_type
         self.result_type = result_type
 
+    @property
+    def hook_type(self) -> str:
+        """Primary hook type (first in list). For backward compatibility."""
+        return self.hook_types[0] if self.hook_types else ""
+
+    def matches(self, hook_type: str) -> bool:
+        """Check if this metadata handles the given hook type."""
+        return hook_type in self.hook_types
+
 
 def hook(
-    hook_type: str,
+    hook_type: Union[str, Sequence[str]],
     payload_type: Optional[Type[P]] = None,
     result_type: Optional[Type[R]] = None,
 ) -> Callable[[Callable], Callable]:
     """Decorator to mark a method as a plugin hook handler.
 
     This decorator attaches metadata to a method so the Plugin class can
     discover it during initialization and register it with the appropriate
-    hook type.
+    hook type(s).
 
     Args:
-        hook_type: The hook type identifier (e.g., 'tool_pre_invoke')
-        payload_type: Optional payload class for registering new hook types
-        result_type: Optional result class for registering new hook types
+        hook_type: One or more hook type identifiers. Pass a string for
+            a single hook, or a list/tuple to register the same method
+            for multiple hook points.
+        payload_type: Optional payload class for registering new hook types.
+        result_type: Optional result class for registering new hook types.
 
     Returns:
-        Decorator function that marks the method with hook metadata
+        Decorator function that marks the method with hook metadata.
 
     Examples:
-        Override method name::
+        Single hook::
 
             @hook(ToolHookType.TOOL_PRE_INVOKE)
             def my_custom_method_name(self, payload, context):
                 return ToolPreInvokeResult(continue_processing=True)
 
+        Multiple hooks (same method handles both)::
+
+            @hook([CmfHookType.TOOL_PRE_INVOKE, CmfHookType.TOOL_POST_INVOKE])
+            def evaluate(self, payload, context):
+                return MessageResult()
+
         Register new hook type::
 
             @hook("email_pre_send", EmailPayload, EmailResult)
@@ -123,8 +140,13 @@ def decorator(func: Callable) -> Callable:
         Returns:
             The same function with metadata attached
         """
-        # Store metadata on the function object
-        metadata = HookMetadata(hook_type, payload_type, result_type)
+        # Normalize to list
+        if isinstance(hook_type, str):
+            types = [hook_type]
+        else:
+            types = list(hook_type)
+
+        metadata = HookMetadata(types, payload_type, result_type)
         setattr(func, _HOOK_METADATA_ATTR, metadata)
         return func
 
@@ -147,6 +169,8 @@ def get_hook_metadata(func: Callable) -> Optional[HookMetadata]:
         >>> metadata = get_hook_metadata(test_func)
         >>> metadata.hook_type
         'test_hook'
+        >>> metadata.matches("test_hook")
+        True
         >>> get_hook_metadata(lambda: None) is None
         True
     """

cpex/framework/extensions/delegation.py

@@ -0,0 +1,121 @@
+# -*- coding: utf-8 -*-
+"""Location: ./cpex/framework/extensions/delegation.py
+Copyright 2025
+SPDX-License-Identifier: Apache-2.0
+Authors: Teryl Taylor
+
+Delegation extension models.
+Carries the delegation chain state through the CMF message for policy
+evaluation. The chain grows monotonically — each hop appends, never
+removes. Scope narrowing is enforced at the framework level.
+
+See: docs/delegation-hooks-design.md
+"""
+
+# Standard
+from datetime import datetime
+
+# Third-Party
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class DelegationHop(BaseModel):
+    """One hop in the delegation chain.
+
+    Each hop represents one step: "entity X delegated to entity Y
+    for audience Z with these scopes." Immutable once created.
+
+    Attributes:
+        subject_id: Who is acting at this hop.
+        subject_type: Entity kind (user, agent, service).
+        audience: Target audience for this hop's token.
+        scopes_granted: What this hop's token can do.
+        timestamp: When this hop was created.
+        ttl_seconds: Token lifetime for this hop.
+        strategy: How the token was obtained (token_exchange, ucan, etc.).
+        from_cache: Whether the token came from cache.
+
+    Examples:
+        >>> hop = DelegationHop(
+        ...     subject_id="alice@corp.com",
+        ...     subject_type="user",
+        ...     scopes_granted=("read:compensation",),
+        ...     timestamp=datetime(2025, 1, 1),
+        ...     strategy="token_exchange",
+        ... )
+        >>> hop.subject_id
+        'alice@corp.com'
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    subject_id: str = Field(description="Who is acting at this hop.")
+    subject_type: str = Field(description="Entity kind: user, agent, service, system.")
+    audience: str | None = Field(default=None, description="Target audience for this hop's token.")
+    scopes_granted: tuple[str, ...] = Field(default=(), description="Scopes this hop's token grants.")
+    timestamp: datetime = Field(default_factory=datetime.utcnow, description="When this hop was created.")
+    ttl_seconds: int | None = Field(default=None, description="Token lifetime in seconds.")
+    strategy: str | None = Field(default=None, description="Token strategy: token_exchange, ucan, passthrough, etc.")
+    from_cache: bool = Field(default=False, description="Whether the token came from cache.")
+
+
+class DelegationExtension(BaseModel):
+    """Delegation chain state carried in the CMF message.
+
+    Mutability tiers:
+    - chain: monotonic (grows with each hop, never shrinks)
+    - origin_subject_id, delegated: immutable (set at first delegation)
+    - actor_subject_id: updates per hop (current actor changes)
+
+    The chain is available to the DSL via the delegation.* namespace:
+        delegation.origin, delegation.actor, delegation.depth,
+        delegation.age, delegated
+
+    Attributes:
+        chain: Ordered list of delegation hops (monotonic growth).
+        depth: Number of hops in the chain.
+        origin_subject_id: Original caller (immutable once set).
+        actor_subject_id: Current actor (latest hop's subject).
+        delegated: Whether this request is delegated.
+        age_seconds: Seconds since the original delegation.
+
+    Examples:
+        >>> ext = DelegationExtension()
+        >>> ext.delegated
+        False
+        >>> ext.depth
+        0
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    chain: tuple[DelegationHop, ...] = Field(default=(), description="Ordered delegation hops.")
+    depth: int = Field(default=0, description="Number of hops.")
+    origin_subject_id: str | None = Field(default=None, description="Original caller.")
+    actor_subject_id: str | None = Field(default=None, description="Current actor.")
+    delegated: bool = Field(default=False, description="Whether this is a delegated request.")
+    age_seconds: float = Field(default=0.0, description="Seconds since original delegation.")
+
+    def with_new_hop(self, hop: DelegationHop) -> "DelegationExtension":
+        """Create a new DelegationExtension with an appended hop.
+
+        Returns a new instance — the original is unchanged (immutable).
+        The framework enforces scope narrowing before calling this.
+
+        Args:
+            hop: The new delegation hop to append.
+
+        Returns:
+            New DelegationExtension with the hop appended.
+        """
+        new_chain = self.chain + (hop,)
+        origin = self.origin_subject_id or hop.subject_id
+        age = (datetime.utcnow() - self.chain[0].timestamp).total_seconds() if self.chain else 0.0
+        return DelegationExtension(
+            chain=new_chain,
+            depth=len(new_chain),
+            origin_subject_id=origin,
+            actor_subject_id=hop.subject_id,
+            delegated=True,
+            age_seconds=age,
+        )

cpex/framework/extensions/extensions.py

@@ -19,6 +19,7 @@
 # First-Party
 from cpex.framework.extensions.agent import AgentExtension
 from cpex.framework.extensions.completion import CompletionExtension
+from cpex.framework.extensions.delegation import DelegationExtension
 from cpex.framework.extensions.framework import FrameworkExtension
 from cpex.framework.extensions.http import HttpExtension
 from cpex.framework.extensions.llm import LLMExtension
@@ -82,6 +83,7 @@ class Extensions(BaseModel):
     agent: AgentExtension | None = Field(default=None, description="Agent execution context.")
     http: HttpExtension | None = Field(default=None, description="HTTP request context.")
     security: SecurityExtension | None = Field(default=None, description="Security labels and identity.")
+    delegation: DelegationExtension | None = Field(default=None, description="Delegation chain state.")
     mcp: MCPExtension | None = Field(default=None, description="MCP entity metadata.")
     completion: CompletionExtension | None = Field(default=None, description="LLM completion information.")
     provenance: ProvenanceExtension | None = Field(default=None, description="Origin and threading.")