OpenAI Agents Can Swap Tools Mid-Session. Can Permissions Keep Up?

At 10:02, a support agent could search customers and read open cases.

At 10:06, the application added two tools to the same session:

issue_refund
close_account

The conversation did not restart. The customer context, earlier instructions, and read-only approval were still there.

The agent now had a different job without receiving a new identity.

OpenAI’s Python SDK 3.42.0, released on October 31, 2026, added agent-session tool settings. The current Agents API reference says an update can replace a session’s tools.

Functions and MCP servers change on the next model call, while built-in tools change by the next turn.

That creates a security question that cannot be solved inside the prompt:

When the available tools change, which earlier decisions are still valid?

A Tool Update Is a Replacement

The update operation does not append one harmless capability. The submitted array replaces the session’s tool list.

Omitting tools keeps the current list. Sending null or an empty array clears it.

An abbreviated request has this shape:

POST /v1/agents/sessions/session_123
Authorization: Bearer $OPENAI_API_KEY
Content-Type: application/json

{
  "agent": {
    "tools": [
      { "type": "function", "name": "search_cases" },
      { "type": "function", "name": "issue_refund" }
    ]
  }
}

Before the update, the agent could inspect a customer case.

After the update, it could move money.

If the application stores only session_id, it has no durable record showing that the session’s authority changed.

Permission Has Three Clocks

I find it useful to treat a live agent session as three clocks that can move independently.

The conversation clock contains what the user requested, what the model learned, and what earlier turns decided.

The capability clock represents the tools, schemas, and credentials currently available.

The authority clock represents the user’s current role, tenant, approval, and policy version.

A session is safe only when those clocks agree at execution time.

The conversation might say, “The supervisor approved this case,” while the tool arguments now refer to another customer.

A tool might still exist while its credential gains a wider scope.

Neither situation requires malicious behavior. Stale state is enough.

Bind Approval to a Capability Snapshot

An approval should cover one concrete action under one known capability set. It should not become permanent permission attached to an entire conversation.

One control is to create a fingerprint whenever the tool registry changes:

import hashlib
import json


def capability_fingerprint(tools: list[dict]) -> str:
    snapshot = [
        {
            "name": tool["name"],
            "schema": tool["schema"],
            "risk": tool["risk"],
            "credential_scope": tool["credential_scope"],
        }
        for tool in sorted(tools, key=lambda item: item["name"])
    ]

    encoded = json.dumps(
        snapshot,
        sort_keys=True,
        separators=(",", ":"),
    )

    return hashlib.sha256(encoded.encode()).hexdigest()

Store that fingerprint with the proposed action and approval:

approval = {
    "principal_id": "user_42",
    "tenant_id": "tenant_acme",
    "tool": "issue_refund",
    "arguments_hash": "sha256:7c1...",
    "capability_fingerprint": "sha256:a84...",
    "policy_version": 17,
    "expires_at": "2026-11-05T11:15:00Z",
}

Before execution, compare that record with the current identity, tenant, arguments, policy, and capability fingerprint.

A relevant mismatch should invalidate the approval and create a new review request.

This prevents an old decision from silently authorizing a changed system.

The Executor Still Owns the Boundary

The model may request issue_refund.

The tool handler must decide whether that request is allowed.

That decision should use server-derived identity and tenant context, not values supplied by the model. It should also enforce business limits and prevent duplicate execution through a stable operation ID.

OpenAI’s MCP guidance provides allowed_tools for restricting what an agent can discover and call. It also recommends keeping credentials outside reusable definitions and logs.

However, the application still owns resource-level authorization.

A tool allowlist answers:

Can this agent call the refund tool?

The business policy answers:

Can this user refund this order, for this tenant, for this amount, right now?

Both checks are necessary.

Test the Transition, Not Only Each Tool

Unit tests usually confirm that search_cases works and issue_refund rejects an unauthorized user.

You also need a test for the moment between those states:

def test_old_approval_fails_after_toolset_change():
    tools_v1 = [SEARCH_CASES, ISSUE_REFUND_V1]
    tools_v2 = [SEARCH_CASES, ISSUE_REFUND_V2]

    approval = approve(
        tool="issue_refund",
        capability_fingerprint=capability_fingerprint(tools_v1),
    )

    decision = authorize(
        approval=approval,
        requested_tool="issue_refund",
        current_fingerprint=capability_fingerprint(tools_v2),
    )

    assert decision == "REVIEW_REQUIRED"

Also test:

• A removed tool
• A changed argument schema
• A narrower or broader credential
• An expired approval
• A tenant switch
• A changed policy version

These transitions are where a valid session can become an invalid authority container.

One Current Documentation Warning

As of November 5, 2026, OpenAI’s API reference says session tools can be replaced. The Python SDK release notes also list agent-session tool settings.

However, the separate configuration guide still says tools cannot be updated through that endpoint.

Until the documentation is consistent, pin the SDK version, test the behavior in a disposable session, and recheck the API reference before deployment.

Tool Changes Are Policy Changes

Swapping tools mid-session can support phased workflows and keep one conversation alive across different tasks.

It should receive the same security treatment as changing an API permission or production role.

For teams planning to hire AI engineers, this also creates a useful interview exercise:

Give a candidate a read-only agent session, add a write tool, and ask which stored decisions must be invalidated.

Their answer will reveal more about production readiness than another prompt-engineering demonstration.

An agent session may keep its history when its tools change. Its authority should not silently survive a meaningful capability change.

What would your application invalidate when a live agent receives a more powerful tool?