Handoff Tool Policy

Secure tool boundaries when one agent hands off to another

Tool policy limits which tools the target agent can use during a handoff — so a low-trust gatekeeper cannot escalate privileges by handing off to a powerful automation agent.

Handoffs are secure by default since PR #1848. The target agent only receives tools shared with the source agent. Use tool_policy_mode="passthrough" only when you intentionally need legacy behaviour.

from praisonaiagents import Agent, handoff, tool

@tool
def search_tool(query: str) -> str:
    """Search the knowledge base."""
    return f"Results for: {query}"

gatekeeper = Agent(name="Gatekeeper", tools=[search_tool])
automation = Agent(name="Automation", tools=[search_tool])

triage = Agent(
    name="Triage",
    handoffs=[handoff(automation)],
)

triage.start("Find policy docs and hand off to automation")

The user asks the triage agent; tool policy limits what the target can run during handoff.

Quick Start

1. Secure by default

   No extra configuration needed — handoff(target) already enforces intersect mode.

   from praisonaiagents import Agent, handoff, tool
   
   @tool
   def search_tool(query: str) -> str:
       """Search the knowledge base."""
       return f"Results for: {query}"
   
   @tool
   def execute_code(code: str) -> str:
       """Run code in a sandbox."""
       return "executed"
   
   gatekeeper = Agent(name="Gatekeeper", tools=[search_tool])
   automation = Agent(name="Automation", tools=[search_tool, execute_code])
   
   triage = Agent(
       name="Triage",
       handoffs=[handoff(automation)],  # automation only gets search_tool during handoff
   )
   
2. Block dangerous tools

   Always strip specific tool names regardless of mode.

   from praisonaiagents import Agent, handoff
   
   triage = Agent(
       name="Triage",
       handoffs=[handoff(automation, blocked_tools=["execute_code"])],
   )
   
3. Opt into legacy passthrough

   Passthrough gives the target its full tool set (minus blocked_tools). Only use this when the source agent is intentionally delegating more capability than it holds.

   from praisonaiagents import Agent, handoff
   
   triage = Agent(
       name="Triage",
       handoffs=[
           handoff(
               automation,
               tool_policy_mode="passthrough",
               blocked_tools=["execute_code"],
           ),
       ],
   )
   
4. Full HandoffConfig

   from praisonaiagents import Agent, handoff, HandoffConfig, HandoffToolPolicy
   
   config = HandoffConfig(
       tool_policy=HandoffToolPolicy(
           mode="intersect",
           blocked_tools=["execute_code", "shell_access"],
       ),
   )
   
   triage = Agent(
       name="Triage",
       handoffs=[handoff(automation, config=config)],
   )
   

How It Works

Modes

Mode	Default?	Target tool set	Use when
intersect	✅ Yes	Tools both agents have, minus blocked_tools	Multi-agent systems with mixed trust levels (recommended)
passthrough	No (opt-in)	Target’s own tools minus blocked_tools	Legacy code, or intentional capability delegation

Configuration Options

HandoffToolPolicy

Option	Type	Default	Description
mode	Literal["intersect", "passthrough"]	"intersect"	How tools are filtered during handoff
blocked_tools	List[str]	[]	Tool names always stripped regardless of mode

handoff() shorthand kwargs

Parameter	Type	Default	Description
tool_policy_mode	Optional[Literal["intersect","passthrough"]]	None	Shorthand for config.tool_policy.mode
blocked_tools	Optional[List[str]]	None	Shorthand for config.tool_policy.blocked_tools

Common Patterns

Gatekeeper → automation (secure default)

from praisonaiagents import Agent, handoff, tool

@tool
def search_tool(query: str) -> str:
    return f"Results for: {query}"

@tool
def execute_code(code: str) -> str:
    return "executed"

gatekeeper = Agent(name="Gatekeeper", tools=[search_tool])
automation = Agent(name="Automation", tools=[search_tool, execute_code])

router = Agent(name="Router", handoffs=[handoff(automation)])

Always block destructive tools

router = Agent(
    name="Router",
    handoffs=[
        handoff(
            automation,
            blocked_tools=["execute_code", "shell_access", "delete_file"],
        ),
    ],
)

Passthrough with selective block list

router = Agent(
    name="Router",
    handoffs=[
        handoff(
            automation,
            tool_policy_mode="passthrough",
            blocked_tools=["execute_code"],
        ),
    ],
)

Best Practices

Default to intersect for least-privilege

Leave tool_policy_mode unset unless you have a specific reason to use passthrough. Intersect mode prevents silent privilege escalation.

Always block known dangerous tools

Even in intersect mode, add blocked_tools for tools like execute_code or shell_access if they appear in the shared set.

Fix the source toolset, not the policy

If intersect mode leaves the target without a needed tool, add that tool to the source agent rather than switching to passthrough.

Test handoff boundaries in security tests

Verify that a gatekeeper handoff cannot invoke tools the source agent does not hold.

Migration Note

Behaviour change (non-breaking API). Before PR #1848, handoffs passed the target agent’s full tool set. After PR #1848, the default is intersection. Existing code runs without changes, but the effective tool set during handoff is narrower. Restore legacy behaviour with one line: tool_policy_mode="passthrough".

Related

Agent Handoffs

Core handoff patterns and delegation

Handoff Filters

Filter context passed during handoff

Handoff Configuration

Full HandoffConfig reference