🪬 fix: Enforce Tool Approval Policy on Headless Agent Runs

[lia-by-librechat]

Summary

An enabled endpoints.agents.toolApproval policy was installed only when the run caller supported interactive pause/resume. The two API-key Chat Completions and Responses endpoints do not implement that lifecycle, so they never registered the policy's PreToolUse hooks. In particular, an administrator's hard deny and dontAsk rules did not reach tools invoked by those endpoints.

Build the same policy hooks for every run with an enabled policy. Keep the humanInTheLoop switch and durable checkpointer exclusive to interactive callers. The SDK blocks a deny before tool execution and, without a resume surface, also blocks ask rather than emitting an unresolved interrupt. Explicit allows and the enabled: false opt-out retain their configured behavior. The same run-wide hook follows lazy subagent MCP alias discovery and registered programmatic approval hooks.

Reported by Chengzhi Yi (@Tardfyou). Related to the Agents API compatibility track.

Mechanism

interactive chat:  enabled policy -> PreToolUse hooks + HITL pause + checkpointer
API-key ingress:  enabled policy -> PreToolUse hooks; ask/deny block; no pause
policy disabled:  no PreToolUse approval hook or HITL machinery

No new handler, authorization model, transport, or configuration option is introduced. This does not make the API-key endpoints capable of obtaining human approval.

Verification

• Reproduced the missing headless decisions before the fix.
• Run-configuration regression covers hard deny precedence, dontAsk allow/deny, default ask, disabled policy, registered programmatic hooks, and lazy MCP alias healing under both interactive and headless runs.
• Real SDK direct-tool test proves a denied tool body does not execute, including when the decision would otherwise ask.
• packages/api typecheck, package build, policy suites, touched-file lint/imports, and static checks run locally. Endpoint controller suites run against the rebuilt package.

Risk / Rollout

Deployments with tool approval already enabled may now see previously unreviewed headless tools blocked. That is the intentional fail-closed behavior; operators can explicitly allow trusted tools or disable the endpoint policy. The default-off configuration is unchanged. Canary is a separate branch and does not receive this dev PR automatically; include it in the next release only after a canary integration decision.

[lia-by-librechat]

Review handoff for exact pushed head 856c7a15fbf94d75f0ea83b472f89f4ac556805e: all enabled run-level tool-approval policies now install PreToolUse hooks for API-key ingresses without enabling interactive pause/checkpointer. Focus on hard deny precedence, headless ask denial, lazy MCP alias healing and SDK direct-tool no-execution tests. Canary remains separate from this dev PR.

[danny-avila]

@codex review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-28T21:22:10.401376Z	856c7a1	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🚀

Reviewed commit: 856c7a15fb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".