app-server README turn/start example uses invalid approvalPolicy value
Open 💬 3 comments Opened Jun 1, 2026 by bar-d
What happened?
The app-server README's turn/start example uses:
"approvalPolicy": "unlessTrusted"
The current TurnStartParams schema accepts the string values:
untrustedon-failureon-requestnever
or a granular approval-policy object. unlessTrusted does not appear to be a valid value.
Expected behavior
The README example should use a valid approvalPolicy value such as on-request, untrusted, on-failure, or never, or show the current granular object form.
Additional context
I searched open issues and PRs for terms including app-server README, approvalPolicy, unlessTrusted, and TurnStartParams, and did not find an existing open item that appears to cover this invalid example value.
3 Comments
I've implemented a fix for this in my fork: https://github.com/kiankhooban/codex/tree/fix/app-server-readme-docs — replaces the invalid
"unlessTrusted"with"on-request"in theturn/startexample. Happy to submit a PR if the repo opens contributions.Confirmed against source — this is a real invalid example value.
In the
turn/startexample,approvalPolicymaps toAskForApproval(codex-rs/app-server-protocol/src/protocol/v2/shared.rs:162). It is serialized with#[serde(rename_all = "kebab-case")], and theUnlessTrustedvariant is explicitly#[serde(rename = "untrusted")], so the valid string values are:(plus the experimental
granularobject form)So
"approvalPolicy": "unlessTrusted"is not a valid value; it should be"untrusted":For reference, the
thread/startexample earlier in the same README already uses a valid value ("approvalPolicy": "never"), so this is isolated to theturn/startexample.Same class of fix as #25545 (
sandbox: "workspaceWrite"→"workspace-write").I checked this against the current
mainsnapshot and the generated app-server protocol types.TurnStartParams.approvalPolicyis typed asAskForApproval, and the generated TypeScript currently accepts"untrusted","on-request","never", or the granular object form. I do not see"unlessTrusted"in the generated schema, so the README example looks stale.While checking the same README, I also noticed two nearby doc/schema mismatches that correspond to open issues #25567 and #25572:
feedback/uploaddocumentsconversation_id, whileFeedbackUploadParamsexposesthreadId.fs/watchis documented as returning a canonicalized path, but the implementation returns the requested absolute path (Ok(FsWatchResponse { path: params.path })).A minimal patch would be:
I saw the contributing guide says external PRs are invitation-only, so I am leaving this as issue analysis rather than opening an unsolicited PR. Happy to submit the focused docs patch if a maintainer wants it.