Skip to content

Python: [BREAKING] Allowlist caller fields in Foundry Responses hosting - #9661

Closed
Darren Cohen (dargilco) wants to merge 15 commits into
microsoft:mainfrom
dargilco:dargilco/foundry-hosting-reject-caller-tool-context
Closed

Darren Cohen (dargilco) wants to merge 15 commits into
microsoft:mainfrom
dargilco:dargilco/foundry-hosting-reject-caller-tool-context

Conversation

@dargilco

@dargilco Darren Cohen (dargilco) commented Oct 24, 2026 •

Copy link
Copy Markdown
Member

The PR was replaced by this new PR: #10348

Motivation & Context

ResponsesHostServer converts caller-supplied Responses fields into Agent Framework run options. Previously, fields not explicitly treated as host-controlled could flow through to the agent, including additional_function_arguments supplied at the root or inside extra_body. That option can populate FunctionInvocationContext.kwargs for tool calls, allowing caller-provided values to override trusted tool context. A field-specific rejection does not protect against other unrecognized or newly added request fields.

This change makes the Responses boundary fail closed by default: only explicitly allowed top-level fields and extra_body keys reach the run options. Developers can still opt individual fields in through the existing prepare_options hook. This PR changes the Responses endpoint; Invocations and direct Agent Framework run APIs are unchanged.

Description & Review Guide

  • What are the major changes?
    • Replaced the field-specific rejection with separate default allowlists for top-level Responses fields and extra_body keys. The allowlists are exposed as read-only frozenset constants from agent_framework_foundry_hosting:
      from agent_framework_foundry_hosting import (
          DEFAULT_CALLER_ALLOWED_EXTRA_BODY_FIELDS,
          DEFAULT_CALLER_ALLOWED_FIELDS,
          ResponsesHostServer,
      )
      
      server = ResponsesHostServer(agent, prepare_options=prepare_options)
      Inspect the two constants to discover the default field policy. They describe defaults, not hook-specific opt-ins.
    • Only allowlisted fields are translated into run options. Other caller fields are rejected by presence, including when their value is null. The same check applies to regular-agent Responses requests, legacy WorkflowAgent requests, and native workflow requests. A rejected request fails before the agent or workflow runs; a rejected approval resume does not consume the pending approval.
    • The root request and extra_body use different lists because they have different roles. Native request fields are translated to Agent Framework option names (including max_output_tokens to max_tokens and parallel_tool_calls to allow_multiple_tool_calls); allowed flattened extra_body values overlay translated options. Unlisted-name collision checks prevent an allowed alias from authorizing a separate unlisted caller field.
    • The existing prepare_options hook can opt an unlisted field into a request by returning it as a run option. Host-controlled fields remain prohibited. This hook is available for regular agents and native workflows, but not legacy WorkflowAgent hosting. Applications opting in caller-derived data must validate it before using it as trusted context.
    • Updated package documentation and added request-, HTTP-, and native-workflow-level tests for rejected fields, null values, alias collisions, hook opt-ins, and approval resume.
  • What is the impact of these changes?
    • This is a behavior change: caller fields outside the defaults that previously flowed through now receive a failed Responses result. In particular, fields such as instructions and tools are not in the default lists. Applications that need an unlisted field must explicitly handle it through prepare_options where that hook is supported.
    • model remains in both default allowlists. This PR does not prevent caller model selection and does not resolve reports specifically about model overrides.
    • The public constants are immutable snapshots of the default policy; future releases may add allowed fields, while removing a field is a breaking change. They do not reflect per-request hook opt-ins. The policy checks field names, not arbitrary values or nested content within allowed fields.
    • The Invocations endpoint, direct Agent.run(..., function_invocation_kwargs=...), and other hosting surfaces are outside this PR's changes.
  • What do you want reviewers to focus on?
    • Whether the default root and extra_body memberships are correct and whether their compatibility impact is intentional.
    • Whether the hook opt-in behavior and its differences between regular agents, native workflows, and legacy WorkflowAgent hosting are clear and safe.
    • Whether other HTTP-facing hosting surfaces need a separate field-boundary review; they are not changed here.

Open Issues

  • Default allowlist membership: A decision is still needed on exactly which fields belong in the default top-level and extra_body allowlists. Each allowed field is something any caller can control on every request, so the defaults should include only fields that are safe for a caller to set without host validation. Each excluded field is a compatibility cost for clients that send it today. Once a stable release ships, adding fields remains possible, but removing one is a breaking change, so the initial lists should err on the side of being small.
    • model is the most important example. As implemented, model remains in both lists, so callers can still choose which model the hosted agent uses, which can affect cost, quotas, capabilities, and safety behavior. Removing it would prevent caller-selected models, but the AgentServer SDK inserts a model value during request normalization (the configured server default or an empty string); any stricter policy must distinguish that SDK-supplied value from a caller-selected model. No decision to disallow models has been made.
  • Reject vs. silently drop unlisted fields: A decision is still needed on how to handle a caller-supplied request field that is not in the allowlist. As implemented, the request fails with an error, which makes the policy visible to callers and avoids silently changing request semantics, but breaks existing clients (including SDKs that send extra fields by default) until the field is allowed or the hook opts it in. The alternative is to strip unlisted fields and continue the run without an error, which is more compatible but hides from callers that part of their request was ignored. A middle option is to strip and log a warning, possibly configurable per host.
  • Invocations protocol: A decision is still needed on whether the Invocations endpoint (InvocationsHostServer) needs the same treatment. It currently passes caller options to agent.run(options=...) after checking only a short list of agent-controlled fields, so other options are accepted. That includes agent-specific options such as MCP server definitions, hooks, provider endpoints and credentials, and permission or sandbox settings. A matching default allowlist with prepare_options opt-in is likely warranted, in a follow-up PR. It should share the decisions above (membership, model, reject vs. drop) so both endpoints behave consistently. Fields such as MCP servers or providers may also need value-level validation, not just name-level allowlisting, when a host intentionally opts them in.

Related Issue

Coordinating with maintainers; the issue link will be added here.

AI Assistance

  • No material AI assistance was used.
  • This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: Implementation, tests, README text, and this PR description were drafted with GitHub Copilot and reviewed by the author.

Contribution Checklist

  • The code builds clean without any errors or warnings
  • All unit tests pass, and I have added new tests where possible
  • The PR follows the Contribution Guidelines
  • This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
  • This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

…quests

ResponsesHostServer now rejects additional_function_arguments supplied at the top level or in extra_body, including on approval resume, so callers cannot replace host-configured tool context. Developer defaults and prepare_options hooks can still supply trusted values.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings October 24, 2026 00:50
@agent-framework-automation agent-framework-automation Bot added documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs python Usage: [Issues, PRs], Target: Python breaking change Usage: [PRs], Target: all PRs that introduce changes that are not backward compatible labels Oct 24, 2026
@dargilco
Darren Cohen (dargilco) marked this pull request as ready for review October 24, 2026 00:54

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The security boundary governing tool context during approval resumes warrants final maintainer review.

2 open issues
What changed in this PR

This PR strengthens the Foundry Responses endpoint’s trust boundary by rejecting caller-supplied tool execution context while preserving developer-controlled configuration.

Changes:

  • Rejects additional_function_arguments at the request’s top level or inside extra_body, including null values.
  • Adds regression coverage for streaming, trusted hooks, and approval resumes.
  • Documents the breaking behavior and supported ways to supply trusted context.
File Description
python/​packages/​foundry_hosting/​tests/​test_responses.py Adds HTTP-level context-injection and approval-resume tests.
python/​packages/​foundry_hosting/​tests/​test_request.py Tests field rejection and trusted hook configuration.
python/​packages/​foundry_hosting/​README.md Documents the restriction and trusted alternatives.
python/​packages/​foundry_hosting/​agent_framework_foundry_hosting/​_request.py Rejects caller-controlled tool context during option translation.

Review effort: Balanced

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (1 commit(s)): e67aef89e000
Model: gpt-5.6-sol

Overview

The change blocks caller-controlled tool context before option hooks, approval consumption, model calls, and tool execution for regular agents and native workflows, with focused coverage for both request locations, response modes, trusted hooks, and approval resume. The remaining gap is the legacy WorkflowAgent Responses path, which bypasses the new validator and can execute a request that the documented endpoint contract says must fail.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
1 verified finding remained after source verification (1 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py

… module

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
… requests

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ackages' conftest

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
_NATIVE_FIELDS = frozenset(CreateResponse.__annotations__)
# Trusted tool-execution context that callers must not supply. Unlike ``_HOST_CONTROLLED_FIELDS``, a developer
# ``prepare_options`` hook may still set it from trusted host state.
_CALLER_REJECTED_FIELDS = frozenset({"additional_function_arguments"})

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what I miss in this, is the broader discussion on if WE should decide which options get rejected or the creator of the server, I think it should be the latter (which is also how the hosting packages work), because there are good reasons to either allow this to be passed through and handled in your code (maybe the user adds a middleware that unpacks this so that non-openAI responses parameters can be passed through through this mechanism. and in general so that as the creator of the server you can enhance the behavior over the existing protocol without having to go fully into the native mode or skipping FHA altogether.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for your comment Eduard van Valkenburg (@eavanvalkenburg)! In the spirit of "secure by default", I'm wondering if additional_function_arguments should be rejected by default, but a hosted agent library setting can allow it for advanced developers where the author "opts-in" by overriding this default. And we clearly document the risk associated with opting in. Let's discuss further.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah, I think in general we can do something like that for all the options, there are also instances where it makes sense to reject, alter or allow through any of the other arguments defined by the OAI responses spec and the developer should have control, and I fully agree with a defensive posture as default. Darren Cohen (@dargilco)

@dargilco Darren Cohen (dargilco) changed the title Python: [BREAKING] Reject caller-supplied tool execution context in Responses requests Python: [BREAKING] Allowlist caller fields in Foundry Responses hosting Nov 13, 2026
@dargilco
Darren Cohen (dargilco) deleted the dargilco/foundry-hosting-reject-caller-tool-context branch November 13, 2026 21:24

This branch was successfully deployed

1 active deployment
github-app-auth — 232d511b Deployed Nov 13, 2026 by dargilco via add_label #27837
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

breaking change Usage: [PRs], Target: all PRs that introduce changes that are not backward compatible documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs python Usage: [Issues, PRs], Target: Python

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants