[Lokesh Nelapati (Lokesh118)]

Description

Adds MaximumFunctionCallsPerRequest to toolautocall.Config to allow callers to cap the total cumulative number of tool invocations performed in a single provider tool-calling request (addressing #1202 and achieving parity with Python's max_function_calls).

Summary of Changes

1. Configuration & Documentation:

   • Added MaximumFunctionCallsPerRequest *int to toolautocall.Config.
   • Validates that negative values return a configuration error (MaximumFunctionCallsPerRequest must be 0 or greater).
   • nil preserves the default unlimited behavior.
   • 0 disables automatic function calls while allowing the model to return a final response without schema tools.
   • Documented in godoc that the limit is evaluated before each batch of function calls; if the limit has not been reached, the active batch finishes even if it exceeds the limit. Once reached, subsequent rounds strip schema tools.
   • Documented suspension/resumption semantics: when human approval is required, execution suspends and pre-approval consumed calls carry forward to the resumed turn via the pending approval state. The budget is scoped to a single invocation of this middleware; independent calls — whether from separate user turns, loop middleware re-invocations, or any other upstream caller — each start with a fresh count.

2. Accounting, Batch Handling & Review Follow-ups:

   • Tracks cumulative actual execution attempts (totalFunctionCalls) across iterations.
   • Includes executions that resulted in errors or panics.
   • Excludes functionInvocationStatusNotFound (unknown tools) from execution attempts so models can retry real tools when TerminateOnUnknownCalls=false.
   • Ignores provider-handled function calls (which already contain FunctionResultContent in streamed updates and are not locally executed).
   • Checks budget before dispatching approved calls on re-entry, emitting valid non-execution error results if budget is already exhausted so conversation history remains valid without unwanted tool execution.
   • Preserves safe tools as normal function calls during approval pausing instead of converting them into approval requests.
   • Clears named required tool choice in prepareOptionsForLastIteration when its associated schema tool is stripped even if non-schema tools remain.
   • Scopes budget accounting cleanly to approval transactions: consumed count is saved within pendingApprovalRequestsState upon suspension and restored upon resumption, ensuring independent turns (including sequential runs using context.Background()) start with a fresh budget without session pollution or context hacks.
   • Tracks budget suspension and restoration across native function and hosted-tool approvals without counting hosted executions against the local function call budget.

3. Tests:

   • TestFunctionInvoking_NegativeMaximumFunctionCallsReturnsError
   • TestFunctionInvoking_ZeroMaximumFunctionCallsDisablesAutomaticCallsAndReturnsFinalResponse
   • TestFunctionInvoking_MaximumFunctionCallsCapsSingleCallsPerIteration
   • TestFunctionInvoking_MaximumFunctionCallsAllowsCurrentBatchToFinish
   • TestFunctionInvoking_MaximumFunctionCallsCountsFailedExecutions
   • TestFunctionInvoking_MaximumFunctionCallsCountsPanickingExecutions
   • TestFunctionInvoking_MaximumFunctionCallsIgnoresNotFoundCalls
   • TestFunctionInvoking_MaximumFunctionCallsIgnoresProviderHandledCalls
   • TestFunctionInvoking_MaximumFunctionCallsIncludesApprovedCalls
   • TestFunctionInvoking_ResumedApprovalWithZeroBudgetSkipsExecution
   • TestFunctionInvoking_ZeroBudgetClearsRequiredToolChoiceWhenSchemaToolRemoved
   • TestFunctionInvoking_ResumedApprovalWithOnlyRequestIDRestoresNonzeroBudget
   • TestFunctionInvoking_PendingApprovalBudgetPreservedAcrossUnrelatedRun
   • TestFunctionInvoking_HostedToolApprovalPreservesLocalBudgetWithoutCountingHostedCalls
   • TestFunctionInvoking_MaximumFunctionCallsIndependentRunsWithBackgroundContext
   • TestFunctionInvoking_StaleSessionConsumedIgnoredWithoutApprovalResponse
   • TestFunctionInvoking_SafeToolsNotConvertedToApprovalsAtBudgetLimit
   • TestToolApproval_SharesMaximumFunctionCallsAcrossAutoApprovedReEntries
   • TestToolApproval_SharesMaximumFunctionCallsAcrossHumanApprovalResumption
   • TestLoop_EachIterationReceivesConfiguredPerRequestBudget
   • Ran full test suite (go test ./...) and race detector (go test -race ./agent/harness/...).

Fixes #1202

[Copilot]

🟡 Changes recommended

Tool-call budget enforcement can incorrectly block retries, allow approved calls beyond the limit, and leave an invalid forced tool choice when schema tools are removed.

4 open issues

• Share function-call counts across approval middleware re-entries · New
• Check the call budget before dispatching approved calls · New
• Clear required tool choices when their schema tool is removed · New
• Exclude unknown function results from the execution count · New

What changed in this PR

Adds a configurable tool-call budget to toolautocall, complementing its existing iteration limit and addressing the cost-control use case in #1202.

Changes:

• Adds MaximumFunctionCallsPerRequest, with negative-value validation, an unlimited default, and zero-budget handling.
• Tracks calls across tool rounds, including failures and approved calls, and removes schema tools once the budget is reached while allowing active batches to finish.
• Adds tests for limits, batch overshoot, failed executions, provider-handled calls, and approval resumption.

File	Description
agent/​harness/​toolautocall/​autocall.go	Adds configuration, call accounting, and budget-based loop termination.
agent/​harness/​toolautocall/​autocall_test.go	Tests validation, budget boundaries, batch completion, and execution accounting.
agent/​harness/​toolautocall/​autocall_approval_test.go	Tests counting approved calls toward the budget.

_{Review effort: Max}

[Lokesh Nelapati (Lokesh118)]

@microsoft-github-policy-service agree

[Quim Muntal (qmuntal)]

Don't like passing params around in the context, unless the value they provide is high. I don't think this meets the bar. Any alternative design?

[Lokesh Nelapati (Lokesh118)]

Thanks for the feedback! Updated the design.

I have completely reverted the changes to agent/agent.go to match upstream/main, eliminating RunToken and context injection altogether.

Instead, toolautocall now manages the budget lifecycle strictly through agent.Session, aligning with the existing conventions in toolapproval, filememory, and todo:

1. Approval Resumption & Re-entries: When incoming messages contain approval content (hasAnyApprovalContent(messages) == true)—whether from human approval across turns or an auto-approval loop in toolapproval—toolautocall continues from the session's recorded consumed count.
2. Independent Runs: A new user prompt (hasAnyApprovalContent(messages) == false) resets any leftover state in the session and starts with a fresh budget of 0.
3. Cleanup: At the end of a run, if no pending approval requests were produced, a defer cleans up the state from the session.

Please let me know your thoughts on the updated design, thanks!

[Lokesh Nelapati (Lokesh118)]

Quim Muntal (@qmuntal) could you please review the updated PR? Thanks.

[Copilot]

🟡 Changes recommended

Tool-call budget accounting is lost across approval resumptions and loop iterations, allowing extra executions beyond the configured limit.

5 open issues

• Restore the saved budget after binding approval responses · New
• Keep the tool budget active for the entire agent run · New
• Preserve budget state across native and hosted-tool approvals · New
• Associate deferred budgets with their pending approval groups · New
• Document that the limit is checked between tool batches · New

4 resolved since last review

• Exclude unknown function results from the execution count
• Clear required tool choices when their schema tool is removed
• Check the call budget before dispatching approved calls
• Share function-call counts across approval middleware re-entries

_{Review effort: Max}

[Copilot]

🟡 Changes recommended

Tool-call budgets are incorrectly preserved and scoped across loop re-entry and approval resumptions, allowing execution limits to be bypassed or fresh-turn budgets to be incorrectly reduced.

4 open issues

• Restore budgets only for unsettled approval transactions · New
• Preserve the tool budget across loop re-entry · New
• Refresh saved budgets after local calls in mixed responses · New
• Track consumed budgets per approval transaction · New

5 resolved since last review

• Associate deferred budgets with their pending approval groups
• Preserve budget state across native and hosted-tool approvals
• Keep the tool budget active for the entire agent run
• Restore the saved budget after binding approval responses
• Document that the limit is checked between tool batches

_{Review effort: Max}

[github-actions]

API consistency review

Result	Scope
aligned	public API, user-visible behavior

Changed Go contract

• New toolautocall.Config.MaximumFunctionCallsPerRequest *int. nil means unlimited, 0 disables local calls, and negative values return a config error.
• Cumulative local execution count across iterations, including errors and panics. Unknown-tool and provider-handled calls are excluded. The count is carried across approval suspend/resume.
• Schema tools (and a named required tool choice) are stripped once the limit is reached.

Upstream evidence reviewed

Implementation	Source	Contract checked
Python	_tools.py FunctionInvocationConfiguration.max_function_calls	Optional cumulative cap, default None (unlimited), best-effort batch semantics, then forces a text response
.NET	FunctionInvokingChatClient.cs	Only MaximumIterationsPerRequest and MaximumConsecutiveErrorsPerRequest exist; no cumulative function-call cap
.NET	ToolApprovalAgentOptions.MaxAutoApprovalIterations	Related per-run cap on re-invocations; not the same contract

Assessment

The new option is opt-in with a default of unlimited, which matches Python's max_function_calls default and semantics (cumulative count, best-effort batch, graceful degradation to a text response). I found no .NET counterpart in the reviewed snapshots, so this is a Go/Python capability that is ahead of .NET rather than a divergence from it. Maintainers may want to track a .NET follow-up. No actionable parity issues. The existing parity-approved and public-api-change labels are correct and unchanged.

Generated by Go API Consistency Review Agent · copilot · auto · 39.4 AIC · ⌖ 0.631 AIC · ⊞ 5.2K · ◷