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:

  • untrusted
  • on-failure
  • on-request
  • never

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.

View original on GitHub ↗

3 Comments

kiankhooban · 2 months ago

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 the turn/start example. Happy to submit a PR if the repo opens contributions.

SnowSky1 · 2 months ago

Confirmed against source — this is a real invalid example value.

In the turn/start example, approvalPolicy maps to AskForApproval (codex-rs/app-server-protocol/src/protocol/v2/shared.rs:162). It is serialized with #[serde(rename_all = "kebab-case")], and the UnlessTrusted variant is explicitly #[serde(rename = "untrusted")], so the valid string values are:

untrusted | on-failure | on-request | never

(plus the experimental granular object form)

So "approvalPolicy": "unlessTrusted" is not a valid value; it should be "untrusted":

-    "approvalPolicy": "unlessTrusted",
+    "approvalPolicy": "untrusted",

For reference, the thread/start example earlier in the same README already uses a valid value ("approvalPolicy": "never"), so this is isolated to the turn/start example.

Same class of fix as #25545 (sandbox: "workspaceWrite" → "workspace-write").

313743062-coder · 1 month ago

I checked this against the current main snapshot and the generated app-server protocol types.

TurnStartParams.approvalPolicy is typed as AskForApproval, 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/upload documents conversation_id, while FeedbackUploadParams exposes threadId.
  • fs/watch is documented as returning a canonicalized path, but the implementation returns the requested absolute path (Ok(FsWatchResponse { path: params.path })).

A minimal patch would be:

diff --git a/codex-rs/app-server/README.md b/codex-rs/app-server/README.md
@@
-- `fs/watch` — subscribe this connection to filesystem change notifications for an absolute file or directory path and caller-provided `watchId`; returns the canonicalized `path`.
+- `fs/watch` — subscribe this connection to filesystem change notifications for an absolute file or directory path and caller-provided `watchId`; returns the requested absolute `path`.
@@
-- `feedback/upload` — submit a feedback report (classification + optional reason/logs, conversation_id, and optional `extraLogFiles` attachments array); returns the tracking thread id.
+- `feedback/upload` — submit a feedback report (classification + optional reason/logs, `threadId`, and optional `extraLogFiles` attachments array); returns the tracking thread id.
@@
-    "approvalPolicy": "unlessTrusted",
+    "approvalPolicy": "on-request",

diff --git a/codex-rs/app-server-protocol/src/protocol/v2/fs.rs b/codex-rs/app-server-protocol/src/protocol/v2/fs.rs
@@
-    /// Canonicalized path associated with the watch.
+    /// Requested absolute path associated with the watch.
     pub path: AbsolutePathBuf,

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.