codex

Apply argument comment lint across codex-rs (#14652 )

## Why

Once the repo-local lint exists, `codex-rs` needs to follow the
checked-in convention and CI needs to keep it from drifting. This commit
applies the fallback `/*param*/` style consistently across existing
positional literal call sites without changing those APIs.

The longer-term preference is still to avoid APIs that require comments
by choosing clearer parameter types and call shapes. This PR is
intentionally the mechanical follow-through for the places where the
existing signatures stay in place.

After rebasing onto newer `main`, the rollout also had to cover newly
introduced `tui_app_server` call sites. That made it clear the first cut
of the CI job was too expensive for the common path: it was spending
almost as much time installing `cargo-dylint` and re-testing the lint
crate as a representative test job spends running product tests. The CI
update keeps the full workspace enforcement but trims that extra
overhead from ordinary `codex-rs` PRs.

## What changed

- keep a dedicated `argument_comment_lint` job in `rust-ci`
- mechanically annotate remaining opaque positional literals across
`codex-rs` with exact `/*param*/` comments, including the rebased
`tui_app_server` call sites that now fall under the lint
- keep the checked-in style aligned with the lint policy by using
`/*param*/` and leaving string and char literals uncommented
- cache `cargo-dylint`, `dylint-link`, and the relevant Cargo
registry/git metadata in the lint job
- split changed-path detection so the lint crate's own `cargo test` step
runs only when `tools/argument-comment-lint/*` or `rust-ci.yml` changes
- continue to run the repo wrapper over the `codex-rs` workspace, so
product-code enforcement is unchanged

Most of the code changes in this commit are intentionally mechanical
comment rewrites or insertions driven by the lint itself.

## Verification

- `./tools/argument-comment-lint/run.sh --workspace`
- `cargo test -p codex-tui-app-server -p codex-tui`
- parsed `.github/workflows/rust-ci.yml` locally with PyYAML

---

* -> #14652
* #14651

Michael Bolin · 2026-03-16 16:48:15 -07:00

b77fe8fefe

feat: support skill-scoped managed network domain overrides in skill config (#14522 )

## Summary

This lets skill loading split `permissions.network` into two distinct
pieces:

- `permissions.network.enabled` still feeds the skill
`PermissionProfile` and remains the coarse gate for whether the skill
can use network access at all.
- `permissions.network.allowed_domains` and
`permissions.network.denied_domains` are lifted into a new
`SkillManagedNetworkOverride` so managed-network sessions can start
per-skill scoped proxies with the right domain overrides.

The change also updates `SkillMetadata` construction sites and adds
loader tests covering YAML parsing plus normalization of the network
gate vs. domain override fields.

## Follow-up
A PR that uses the network_override to spin up a skill-specific proxy if
network_override is not none.

Celia Chen · 2026-03-13 04:45:14 +00:00

0c60eea4a5

fix: move inline codex-rs/core unit tests into sibling files (#14444 )

## Why
PR #13783 moved the `codex.rs` unit tests into `codex_tests.rs`. This
applies the same extraction pattern across the rest of `codex-rs/core`
so the production modules stay focused on runtime code instead of large
inline test blocks.

Keeping the tests in sibling files also makes follow-up edits easier to
review because product changes no longer have to share a file with
hundreds or thousands of lines of test scaffolding.

## What changed
- replaced each inline `mod tests { ... }` in `codex-rs/core/src/**`
with a path-based module declaration
- moved each extracted unit test module into a sibling `*_tests.rs`
file, using `mod_tests.rs` for `mod.rs` modules
- preserved the existing `cfg(...)` guards and module-local structure so
the refactor remains structural rather than behavioral

## Testing
- `cargo test -p codex-core --lib` (`1653 passed; 0 failed; 5 ignored`)
- `just fix -p codex-core`
- `cargo fmt --check`
- `cargo shear`

Michael Bolin · 2026-03-12 08:16:36 -07:00

0c8a36676a

feat: Add additional macOS Sandbox Permissions for Launch Services, Contacts, Reminders (#14155 )

Add additional macOS Sandbox Permissions levers for the following:

- Launch Services
- Contacts
- Reminders

Leo Shimonaka · 2026-03-11 12:33:09 -07:00

889b4796fc

core/protocol: add structured macOS additional permissions and merge them into sandbox execution (#13499 )

## Summary
- Introduce strongly-typed macOS additional permissions across
protocol/core/app-server boundaries.
- Merge additional permissions into effective sandbox execution,
including macOS seatbelt profile extensions.
- Expand docs, schema/tool definitions, UI rendering, and tests for
`network`, `file_system`, and `macos` additional permissions.

Celia Chen · 2026-03-05 16:21:45 -08:00

aaefee04cd

chore: Nest skill and protocol network permissions under network.enabled (#13427 )

## Summary

Changes the permission profile shape from a bare network boolean to a
nested object.

Before:

```yaml
permissions:
  network: true
```

After:

```yaml
permissions:
  network:
    enabled: true
```

This also updates the shared Rust and app-server protocol types so
`PermissionProfile.network` is no longer `Option<bool>`, but
`Option<NetworkPermissions>` with `enabled: Option<bool>`.

## What Changed

- Updated `PermissionProfile` in `codex-rs/protocol/src/models.rs`:
- `pub network: Option<bool>` -> `pub network:
Option<NetworkPermissions>`
- Added `NetworkPermissions` with:
  - `pub enabled: Option<bool>`
- Changed emptiness semantics so `network` is only considered empty when
`enabled` is `None`
- Updated skill metadata parsing to accept `permissions.network.enabled`
- Updated core permission consumers to read
`network.enabled.unwrap_or(false)` where a concrete boolean is needed
- Updated app-server v2 protocol types and regenerated schema/TypeScript
outputs
- Updated docs to mention `additionalPermissions.network.enabled`

Celia Chen · 2026-03-03 20:57:29 -08:00

d622bff384

chore: remove SkillMetadata.permissions and derive skill sandboxing from permission_profile (#13061 )

## Summary

This change removes the compiled permissions field from skill metadata
and keeps permission_profile as the single source of truth.

Skill loading no longer compiles skill permissions eagerly. Instead, the
zsh-fork skill escalation path compiles `skill.permission_profile` when
it needs to determine the sandbox to apply for a skill script.

  ## Behavior change

  For skills that declare:
```
  permissions: {}
```
we now treat that the same as having no skill permissions override,
instead of creating and using a default readonly sandbox. This change
makes the behavior more intuitive:

  - only non-empty skill permission profiles affect sandboxing
- omitting permissions and writing permissions: {} now mean the same
thing
- skill metadata keeps a single permissions representation instead of
storing derived state too

Overall, this makes skill sandbox behavior easier to understand and more
predictable.

Celia Chen · 2026-03-03 01:29:53 +00:00

0bb152b01d

feat: load from plugins (#12864 )

Support loading plugins.

Plugins can now be enabled via [plugins.<name>] in config.toml. They are
loaded as first-class entities through PluginsManager, and their default
skills/ and .mcp.json contributions are integrated into the existing
skills and MCP flows.

xl-openai · 2026-03-01 10:50:56 -08:00

752402c4fe

fix: use AbsolutePathBuf for permission profile file roots (#12970 )

## Why
`PermissionProfile` should describe filesystem roots as absolute paths
at the type level. Using `PathBuf` in `FileSystemPermissions` made the
shared type too permissive and blurred together three different
deserialization cases:

- skill metadata in `agents/openai.yaml`, where relative paths should
resolve against the skill directory
- app-server API payloads, where callers should have to send absolute
paths
- local tool-call payloads for commands like `shell_command` and
`exec_command`, where `additional_permissions.file_system` may
legitimately be relative to the command `workdir`

This change tightens the shared model without regressing the existing
local command flow.

## What Changed
- changed `protocol::models::FileSystemPermissions` and the app-server
`AdditionalFileSystemPermissions` mirror to use `AbsolutePathBuf`
- wrapped skill metadata deserialization in `AbsolutePathBufGuard`, so
relative permission roots in `agents/openai.yaml` resolve against the
containing skill directory
- kept app-server/API deserialization strict, so relative
`additionalPermissions.fileSystem.*` paths are rejected at the boundary
- restored cwd/workdir-relative deserialization for local tool-call
payloads by parsing `shell`, `shell_command`, and `exec_command`
arguments under an `AbsolutePathBufGuard` rooted at the resolved command
working directory
- simplified runtime additional-permission normalization so it only
canonicalizes and deduplicates absolute roots instead of trying to
recover relative ones later
- updated the app-server schema fixtures, `app-server/README.md`, and
the affected transport/TUI tests to match the final behavior

Michael Bolin · 2026-02-27 17:42:52 +00:00

d09a7535ed

Surface skill permission profiles in zsh-fork exec approvals (#12753 )

## Summary

- Preserve each skill’s raw permissions block as a permission_profile on
SkillMetadata during skill loading.
- Keep compiling that same metadata into the existing runtime
Permissions object, so current enforcement
    behavior stays intact.
- When zsh-fork intercepts execution of a script that belongs to a
skill, include the skill’s
    permission_profile in the exec approval request.
- This lets approval UIs show the extra filesystem access the skill
declared when prompting for approval.

Celia Chen · 2026-02-25 01:23:10 -08:00

6a3233da64

chore: migrate additional permissions to PermissionProfile (#12731 )

This PR replaces the old `additional_permissions.fs_read/fs_write` shape
with a shared `PermissionProfile`
model and wires it through the command approval, sandboxing, protocol,
and TUI layers. The schema is adopted from the
`SkillManifestPermissions`, which is also refactored to use this unified
struct. This helps us easily expose permission profiles in app
server/core as a follow-up.

Celia Chen · 2026-02-25 03:35:28 +00:00

16ca527c80

fix: clarify the value of SkillMetadata.path (#12729 )

Rename `SkillMetadata.path` to `SkillMetadata.path_to_skills_md` for
clarity.

Would ideally change the type to `AbsolutePathBuf`, but that can be done
later.

Michael Bolin · 2026-02-24 17:15:54 -08:00

448fb6ac22

fix: make skills loader tests hermetic with ~/.agents skills (#12474 )

Michael Bolin · 2026-02-21 14:40:13 -08:00

f33ac830aa

chore: move config diagnostics out of codex-core (#12427 )

## Why

Compiling `codex-rs/core` is a bottleneck for local iteration, so this
change continues the ongoing extraction of config-related functionality
out of `codex-core` and into `codex-config`.

The goal is not just to move code, but to reduce `codex-core` ownership
and indirection so more code depends on `codex-config` directly.

## What Changed

- Moved config diagnostics logic from
`core/src/config_loader/diagnostics.rs` into
`config/src/diagnostics.rs`.
- Updated `codex-core` to use `codex-config` diagnostics types/functions
directly where possible.
- Removed the `core/src/config_loader/diagnostics.rs` shim module
entirely; the remaining `ConfigToml`-specific calls are in
`core/src/config_loader/mod.rs`.
- Moved `CONFIG_TOML_FILE` into `codex-config` and updated existing
references to use `codex_config::CONFIG_TOML_FILE` directly.
- Added a direct `codex-config` dependency to `codex-cli` for its
`CONFIG_TOML_FILE` use.

Michael Bolin · 2026-02-20 23:19:29 -08:00

1a220ad77d

feat: add config allow_login_shell (#12312 )

jif-oai · 2026-02-20 20:02:24 +00:00

5034d4bd89

feat(skills): add permission profiles from openai.yaml metadata (#11658 )

## Summary

This PR adds support for skill-level permissions in .codex/openai.yaml
and wires that through the skill loading pipeline.

  ## What’s included

1. Added a new permissions section for skills (network, filesystem, and
macOS-related access).
2. Implemented permission parsing/normalization and translation into
runtime permission profiles.
3. Threaded the new permission profile through SkillMetadata and loader
flow.

  ## Follow-up

A follow-up PR will connect these permission profiles to actual sandbox
enforcement and add user approval prompts for executing binaries/scripts
from skill directories.


 ## Example 
`openai.yaml` snippet:
```
  permissions:
    network: true
    fs_read:
      - "./data"
      - "./data"
    fs_write:
      - "./output"
    macos_preferences: "readwrite"
    macos_automation:
      - "com.apple.Notes"
    macos_accessibility: true
    macos_calendar: true
```

compiled skill permission profile metadata (macOS): 
```
SkillPermissionProfile {
      sandbox_policy: SandboxPolicy::WorkspaceWrite {
          writable_roots: vec![
              AbsolutePathBuf::try_from("/ABS/PATH/TO/SKILL/output").unwrap(),
          ],
          read_only_access: ReadOnlyAccess::Restricted {
              include_platform_defaults: true,
              readable_roots: vec![
                  AbsolutePathBuf::try_from("/ABS/PATH/TO/SKILL/data").unwrap(),
              ],
          },
          network_access: true,
          exclude_tmpdir_env_var: false,
          exclude_slash_tmp: false,
      },
      // Truncated for readability; actual generated profile is longer.
      macos_seatbelt_permission_file: r#"
  (allow user-preference-write)
  (allow appleevent-send
      (appleevent-destination "com.apple.Notes"))
  (allow mach-lookup (global-name "com.apple.axserver"))
  (allow mach-lookup (global-name "com.apple.CalendarAgent"))
  ...
  "#.to_string(),
```

Celia Chen · 2026-02-14 01:43:44 +00:00

5b6911cb1b

feat: add SkillPolicy to skill metadata and support allow_implicit_invocation (#11244 )

Tested by setting the policy in agents/openai.yaml to true, false, and
leaving it unset (default).
```
policy:
  allow_implicit_invocation: false
```
<img width="847" height="289" alt="Screenshot 2026-02-09 at 3 42 41 PM"
src="https://github.com/user-attachments/assets/d3476264-3355-47cf-894a-4ffba53e3481"
/>

alexsong-oai · 2026-02-09 23:13:27 -08:00

91704c5672

Load requirements on windows (#10770 )

We support requirements on Unix, loading from
`/etc/codex/requirements.toml`. On MacOS, we also support MDM.

Now, on Windows, we'll load requirements from
`%ProgramData%\OpenAI\Codex\requirements.toml`

gt-oai · 2026-02-09 16:05:38 +00:00

9fe925b15a

feat: Read personal skills from .agents/skills (#10437 )

- Issue: https://github.com/agentskills/agentskills/issues/15
- Follow-up to https://github.com/openai/codex/pull/10317 (for team/repo
skills)
- This change now also loads personal/user skills from
`$HOME/.agents/skills` (or `~/.agents/skills`) in addition to loading
from `.agents/skills` inside of git repos.
- The location of `.system` skills remains unchanged.
- Keeping backwards compatibility with `~/.codex/skills` for now until
we fully deprecate.

With skills in both personal folders:
<img width="831" height="421" alt="image"
src="https://github.com/user-attachments/assets/ad8ac918-bfe6-4a2d-8a8e-d608c9d3d701"
/>

We load from both places:
<img width="607" height="236" alt="image"
src="https://github.com/user-attachments/assets/480f4db0-ae64-4dc1-bdf5-c5de98c16f5c"
/>

Gav Verma · 2026-02-02 16:49:23 -08:00

e24058b7a8

feat: Support loading skills from .agents/skills (#10317 )

This PR adds support for loading
[skills](https://developers.openai.com/codex/skills) from
`.agents/skills/`.
- Issue: https://github.com/agentskills/agentskills/issues/15
- Motivation: When skills live on the filesystem, sharing them across
agents is awkward and often ends up requiring symlinks/duplication. A
single location under `.agents/` makes it easier to share skills.
- Loading from `.codex/skills/` will remain but will be deprecated soon.
The change only applies to the [REPO
scope](https://developers.openai.com/codex/skills#where-to-save-skills).
- Documentation will be updated before this change is live.

Testing with skills in two locations of this repo:
<img width="960" height="152" alt="image"
src="https://github.com/user-attachments/assets/28975ff9-7363-46dd-ad40-f4c7bfdb8234"
/>

When starting Codex with CWD in `$repo_root` (should only pick up at
root):
<img width="513" height="143" alt="image"
src="https://github.com/user-attachments/assets/389e1ea7-020c-481e-bda0-ce58562db59f"
/>

When starting Codex with CWD in `$repo_root/codex-rs` (should pick up at
cwd and crawl up to root):
<img width="552" height="177" alt="image"
src="https://github.com/user-attachments/assets/a5beb8de-11b4-45ed-8660-80707c77006a"
/>

Gav Verma · 2026-01-31 18:45:05 -08:00

39a6a84097

load from yaml (#10194 )

alexsong-oai · 2026-01-29 21:44:12 -05:00

d550fbf41a

[skills] Auto install MCP dependencies when running skils with dependency specs. (#9982 )

Auto install MCP dependencies when running skils with dependency specs.

Matthew Zeng · 2026-01-27 19:02:45 -08:00

3bb8e69dd3

Remove load from SKILL.toml fallback (#10007 )

alexsong-oai · 2026-01-27 12:06:40 -08:00

2f8a44baea

feat: load interface metadata from SKILL.json (#9953 )

alexsong-oai · 2026-01-27 01:38:06 +00:00

a641a6427c

still load skills (#9700 )

gt-oai · 2026-01-23 20:35:50 +00:00

c6ded0afd8

Print warning if we skip config loading (#9611 )

https://github.com/openai/codex/pull/9533 silently ignored config if
untrusted. Instead, we still load it but disable it. Maybe we shouldn't
try to parse it either...

<img width="939" height="515" alt="Screenshot 2026-01-21 at 14 56 38"
src="https://github.com/user-attachments/assets/e753cc22-dd99-4242-8ffe-7589e85bef66"
/>

gt-oai · 2026-01-23 20:06:37 +00:00

7938c170d9

Only load config from trusted folders (#9533 )

Config includes multiple code execution entrypoints. 

Now, we load the config from predetermined locations first
(~/.codex/config.toml etc), use those to learn which folders are
'trusted', and only load additional config from the CWD if it is
trusted.

gt-oai · 2026-01-20 15:44:21 +00:00

7351c12999

Support enable/disable skill via config/api. (#9328 )

In config.toml:
```
[[skills.config]]
path = "/Users/xl/.codex/skills/my_skill/SKILL.md"
enabled = false
```

API:
skills/list, skills/config/write

xl-openai · 2026-01-16 20:22:05 -08:00

ad8bf59cbf

Support SKILL.toml file. (#9125 )

We’re introducing a new SKILL.toml to hold skill metadata so Codex can
deliver a richer Skills experience.

Initial focus is the interface block:
```
[interface]
display_name = "Optional user-facing name"
short_description = "Optional user-facing description"
icon_small = "./assets/small-400px.png"
icon_large = "./assets/large-logo.svg"
brand_color = "#3B82F6"
default_prompt = "Optional surrounding prompt to use the skill with"
```

All fields are exposed via the app server API.
display_name and short_description are consumed by the TUI.

xl-openai · 2026-01-15 11:20:04 -08:00

42fa4c237f

Feat: appServer.requirementList for requirement.toml (#8800 )

### Summary
We are exposing requirements via `requirement/list` method from
app-server so that we can conditionally disable the agent mode dropdown
selection in VSCE and correctly setting the default value.

### Sample output
#### `etc/codex/requirements.toml`
<img width="497" height="49" alt="Screenshot 2026-01-06 at 11 32 06 PM"
src="https://github.com/user-attachments/assets/fbd9402e-515f-4b9e-a158-2abb23e866a0"
/>

#### App server response
<img width="1107" height="79" alt="Screenshot 2026-01-06 at 11 30 18 PM"
src="https://github.com/user-attachments/assets/c0d669cd-54ef-4789-a26c-adb2c41950af"
/>

Shijie Rao · 2026-01-07 13:57:44 -08:00

efd0c21b9b

Support symlink for skills discovery. (#8801 )

Skills discovery now follows symlink entries for SkillScope::User
($CODEX_HOME/skills) and SkillScope::Admin (e.g. /etc/codex/skills).

Added cycle protection: directories are canonicalized and tracked in a
visited set to prevent infinite traversal from circular links.

Added per-root traversal limits to avoid accidentally scanning huge
trees:
- max depth: 6
- max directories: 2000 (logs a warning if truncated)

For now, symlink stat failures and traversal truncation are logged
rather than surfaced as UI “invalid SKILL.md” warnings.

xl-openai · 2026-01-07 13:34:48 -08:00

61e81af887

Use ConfigLayerStack for skills discovery. (#8497 )

Use ConfigLayerStack to get all folders while loading skills.

xl-openai · 2026-01-05 13:47:39 -08:00

58a91a0b50

Fix admin skills. (#8305 )

We were assembling the skill roots in two different places, and the
admin root was missing in one of them. This change centralizes root
selection into a helper so both paths stay in sync.

xl-openai · 2025-12-19 04:10:19 +00:00

339b052d68

Support admin scope skills. (#8296 )

a new scope reads from /etc/codex

xl-openai · 2025-12-19 02:28:56 +00:00

8120c8765b

chore: migrate from Config::load_from_base_config_with_overrides to ConfigBuilder (#8276 )

https://github.com/openai/codex/pull/8235 introduced `ConfigBuilder` and
this PR updates all call non-test call sites to use it instead of
`Config::load_from_base_config_with_overrides()`.

This is important because `load_from_base_config_with_overrides()` uses
an empty `ConfigRequirements`, which is a reasonable default for testing
so the tests are not influenced by the settings on the host. This method
is now guarded by `#[cfg(test)]` so it cannot be used by business logic.

Because `ConfigBuilder::build()` is `async`, many of the test methods
had to be migrated to be `async`, as well. On the bright side, this made
it possible to eliminate a bunch of `block_on_future()` stuff.

Michael Bolin · 2025-12-18 16:12:52 -08:00

3d4ced3ff5

Support skills shortDescription. (#8278 )

Allow SKILL.md to specify a more human-readable short description as
skill metadata.

xl-openai · 2025-12-18 23:13:18 +00:00

358a5baba0

Support SYSTEM skills. (#8220 )

1. Remove PUBLIC skills and introduce SYSTEM skills embedded in the
binary and installed into $CODEX_HOME/skills/.system at startup.
2. Skills are now always enabled (feature flag removed).
3. Update skills/list to accept forceReload and plumb it through (not
used by clients yet).

xl-openai · 2025-12-17 18:48:28 -08:00

da3869eeb6

Add public skills + improve repo skill discovery and error UX (#8098 )

1. Adds SkillScope::Public end-to-end (core + protocol) and loads skills
from the public cache directory
2. Improves repo skill discovery by searching upward for the nearest
.codex/skills within a git repo
3. Deduplicates skills by name with deterministic ordering to avoid
duplicates across sources
4. Fixes garbled “Skill errors” overlay rendering by preventing pending
history lines from being injected during the modal
5. Updates the project docs “Skills” intro wording to avoid hardcoded
paths

xl-openai · 2025-12-17 01:35:49 -08:00

4897efcced

Reimplement skills loading using SkillsManager + skills/list op. (#7914 )

refactor the way we load and manage skills:
1. Move skill discovery/caching into SkillsManager and reuse it across
sessions.
2. Add the skills/list API (Op::ListSkills/SkillsListResponse) to fetch
skills for one or more cwds. Also update app-server for VSCE/App;
3. Trigger skills/list during session startup so UIs preload skills and
handle errors immediately.

xl-openai · 2025-12-14 09:58:17 -08:00

5d77d4db6b

Make skill name and description limit based on characters not byte counts (#7915 )

This PR changes the length validation for SKILL.md `name` and
`description` fields so they use character counts rather than byte
counts. Aligned character limits to other harnesses.

This addresses #7730.

Eric Traut · 2025-12-11 22:28:59 -08:00

60479a9674

Also load skills from repo root. (#7645 )

Also load skills from /REPO_ROOT/codex/skills.

xl-openai · 2025-12-05 18:01:49 -08:00

93f61dbc5f

feat: experimental support for skills.md (#7412 )

This change prototypes support for Skills with the CLI. This is an
**experimental** feature for internal testing.

---------

Co-authored-by: Gav Verma <gverma@openai.com>

Thibault Sottiaux · 2025-12-01 20:22:35 -08:00

a8d5ad37b8

42 Commits