Proposed specificationSource-located exemplarH1

Decentralized handoffs

Transfer control to another specialized agent.

JOIN POINTpeer_control_transferRECORD STATUSCandidate · v0.1.0

UML class view

The proposed contract drawn as participant roles, received calls, and numbered dependencies.

Object interactions

The same roles and calls as a class collaboration and a numbered message sequence.

Object interaction diagram for Decentralized handoffs, showing role collaboration and a numbered message sequence — FIG. W07 / OBJECT INTERACTIONS
Open full SVG Download PDF

Pointcut

Where the mechanism applies. All four dimensions belong to the proposed match, not just its vocabulary.

Context: Multiple peer agents can transfer control.
Trigger: The active agent invokes a handoff target.
Structure: Control-transfer envelope, state policy, target criteria, and authority boundary.
Effect: The target becomes active with declared history and no implicit privilege expansion.

Protected contract

The obligation that clients, operators, and auditors should be able to rely on.

Requires: Target identity and transfer trigger are explicit.
Ensures: Handoff records source, target, and transferred state.
Invariant: Control cannot cycle indefinitely or return to an invalid target.
Violation: Unknown targets, disabled handoffs, and loops have defined outcomes.

Negative control

A normal function call that returns to the caller is not a handoff.

Variation & lifecycle

The hot spot is admitted only where the protected semantics survive.

Permitted variation

History filters, target criteria, enable predicates, and cycle controls.

Test obligation

Test transfer, filtered history, disabled target, cycle, and authority.

Evolution question

Did handoffs gain nested history and resumable approval state?

Prompt + code design

An illustrative prompt and a small design sketch for the proposed contract. Names and APIs are invented; this is not a repository excerpt.

PROMPT SKETCH

Hand off control only with an explicit target and trigger. Record the source, target, and transferred state, and enforce a cycle bound so a peer conversation can terminate.

CODE DESIGN / PYTHON

def handoff(session, target, trigger, state):
    if session.handoff_count >= session.max_handoffs:
        raise HandoffLimit(session.id)
    record = HandoffRecord(
        source=session.active_agent,
        target=target,
        trigger=trigger,
        state=state.redact_for(target),
    )
    session.apply(record)
    return target.resume(session)

Illustrative design sketch. A transfer without state or a cycle bound is an unbounded conversation, not coordination. This example is a teaching aid, not implementation evidence or a conformance claim.

Detection & matching

The frozen rule that retrieves this record, the canonical source exemplar, and the control that should stay unmatched.

Join point: peer_control_transfer
Source locator: OpenAI
Lexical cue: (?i)\b(?:hand[_-]?offs?|transfer[_-]?to|transfer[_-]?agent|decentrali[sz]ed[_-]?handoff)\bFrozen expression, v0.1.0. A match is a retrieval cue, not a confirmed implementation.
Aliases: None
Canonical exemplar: openai/openai-agents-pythonsrc/agents/handoffs/__init__.py:127Support: tests/test_handoff_tool.py:1
Negative control: A normal function call that returns to the caller is not a handoff.

Scope-anchored review. pohe-agent analyze <repo> --pattern W07 anchors the cue to its enclosing declaration and checks a separate operational signature for all four pointcut dimensions. Missing roles and negative-control risks remain visible; a structural match is not E2/E3. Calibration report ↗

Repository files

Up to five public files retrieved by the frozen cue and pinned to the audited commit. A match is a place to inspect, not a confirmed implementation.

01openai/openai-agents-pythonsrc/agents/handoffs/__init__.py:127CANONICAL SOURCE 02aaif-goose/goosecrates/goose-agent/src/inference.rs:496RETRIEVAL CUE 03affaan-m/ECCskills/taste-application/scripts/blender_prop.py:10RETRIEVAL CUE 04agno-agi/agnolibs/agno/agno/company/execution.py:15RETRIEVAL CUE 05anomalyco/opencodepackages/ai/src/route/transport/websocket.ts:209RETRIEVAL CUE

Evidence & provenance

Each layer answers a different question. Do not substitute retrieval for review.

Source-located exemplar

A concrete source anchor is available for this proposed record. It is one exemplar, not evidence that all repositories—or every contract field—conform.

Review boundary: this candidate and its specification come from an AI-assisted study. Independent human validation remains open.

ANY-EVIDENCE FAMILY COVERAGE29/36

80.6% of repository families in the frozen panel have at least one current cue, historical cue, or canonical source layer. This is not confirmed prevalence.

Current lexical-cue repositories: 33 / 41

Canonical source anchoropenai/openai-agents-python 86bd29878b30src/agents/handoffs/__init__.py:127

Supporting surfacetests/test_handoff_tool.py:1

Control-transfer handoff contract.

Exploratory retrieval cue Regex / v0.1.0

(?i)\b(?:hand[_-]?offs?|transfer[_-]?to|transfer[_-]?agent|decentrali[sz]ed[_-]?handoff)\b

This expression is a discovery instrument only. A match is a retrieval cue—not a confirmed implementation, pointcut match, or contract proof.