feat: add trusted project instructions mode

README.md

@@ -110,6 +110,7 @@ jobs:
 | `model`                  | Model the agent should use. Leave empty to let Codex pick its default.                                                                         | `""`        |
 | `effort`                 | Reasoning effort the agent should use. Leave empty to let Codex pick its default.                                                              | `""`        |
 | `codex-home`             | Directory to use as the Codex CLI home (config/cache). Uses the CLI default when empty.                                                        | `""`        |
+| `project-instructions-mode` | Source for project instructions. `workspace` preserves current checked-out doc loading; `default-branch` opts into trusted default-branch `AGENTS.override.md` / `AGENTS.md` files. | `workspace` |
 | `safety-strategy`        | Controls how the action restricts Codex privileges. See [Safety strategy](#safety-strategy).                                                   | `drop-sudo` |
 | `codex-user`             | Username to run Codex as when `safety-strategy` is `unprivileged-user`.                                                                        | `""`        |
 | `allow-users`            | List of GitHub usernames who can trigger the action in addition to those who have write access to the repo.                                    | `""`        |
@@ -127,6 +128,13 @@ See [Protecting your `OPENAI_API_KEY`](./docs/security.md#protecting-your-openai
 - **`read-only`** — Executes Codex in a read-only sandbox. Codex can view files but cannot mutate the filesystem or access the network directly. The OpenAI API key still flows through the proxy, so Codex could read it if it can reach process memory.
 - **`unsafe`** — No privilege reduction. Codex runs as the default `runner` user (which typically has `sudo`). Only use this when you fully trust the prompt. On Windows runners this is the only supported choice and the action will fail if another option is provided.
 
+## Project Instructions Mode
+
+`project-instructions-mode` controls whether Codex reads repository instruction files from the checked-out workspace or from a trusted branch. When this input is omitted, the action preserves its current behavior.
+
+- **`workspace` (default)** — Preserves the existing branch-local behavior and lets Codex discover project docs directly from the checkout.
+- **`default-branch`** — Opts into trusted instruction loading. The action fetches trusted `AGENTS.override.md` / `AGENTS.md` files from the repository default branch along the path from the repository root to `working-directory`, writes them into `CODEX_HOME`, disables checked-out project-doc discovery, and clears Codex project trust for that run so project-local `.codex/config.toml` is not loaded. This keeps pull request-controlled instruction/config files out of the model-visible instruction channel for workflows that enable it. In this mode, `codex-home` must stay outside the GitHub workspace.
+
 ### Operating system support
 
 - **Windows**: GitHub-hosted Windows runners lack a supported sandbox. Set `safety-strategy: unsafe`. The action validates this and exits early otherwise.

action.yml

@@ -59,6 +59,19 @@ inputs:
     description: "Directory to use as the Codex home directory. If empty, the default Codex home directory will be used."
     required: false
     default: ""
+  project-instructions-mode:
+    description: |
+      Controls where Codex project instructions come from.
+
+      * `workspace` (default) Load project docs from the checked-out workspace,
+        preserving the current behavior when this input is omitted.
+      * `default-branch` Load trusted `AGENTS.override.md` / `AGENTS.md`
+        files from the repository default branch for the repository path that
+        contains `working-directory`, ignore checked-out project docs, and
+        disable project-local Codex config for the run. `codex-home` must stay
+        outside the GitHub workspace in this mode.
+    required: false
+    default: "workspace"
   safety-strategy:
     description: |
       Specify one of the following options (on Windows, the only supported option is `unsafe`):
@@ -320,6 +333,26 @@ runs:
         fi
         echo "Confirmed sudo privilege is disabled."
 
+    - name: Prepare project instructions
+      if: ${{ (inputs.prompt != '' || inputs['prompt-file'] != '') && inputs['project-instructions-mode'] == 'default-branch' }}
+      shell: bash
+      env:
+        ACTION_PATH: ${{ github.action_path }}
+        CODEX_HOME: ${{ steps.resolve_home.outputs.codex-home }}
+        CODEX_WORKING_DIRECTORY: ${{ inputs['working-directory'] || github.workspace }}
+        CODEX_PROJECT_INSTRUCTIONS_MODE: ${{ inputs['project-instructions-mode'] }}
+        CODEX_SAFETY_STRATEGY: ${{ inputs['safety-strategy'] }}
+        GITHUB_REPOSITORY: ${{ github.repository }}
+        GITHUB_TOKEN: ${{ github.token }}
+        GITHUB_WORKSPACE: ${{ github.workspace }}
+      run: |
+        node "$ACTION_PATH/dist/main.js" prepare-project-instructions \
+            --codex-home "$CODEX_HOME" \
+            --cd "$CODEX_WORKING_DIRECTORY" \
+            --workspace "$GITHUB_WORKSPACE" \
+            --mode "$CODEX_PROJECT_INSTRUCTIONS_MODE" \
+            --safety-strategy "$CODEX_SAFETY_STRATEGY"
+
     - name: Run codex exec
       id: run_codex
       if: ${{ inputs.prompt != '' || inputs['prompt-file'] != '' }}
@@ -337,6 +370,7 @@ runs:
         CODEX_EFFORT: ${{ inputs.effort }}
         CODEX_SAFETY_STRATEGY: ${{ inputs['safety-strategy'] }}
         CODEX_USER: ${{ inputs['codex-user'] }}
+        CODEX_PROJECT_INSTRUCTIONS_MODE: ${{ inputs['project-instructions-mode'] }}
         ACTION_PATH: ${{ github.action_path }}
         FORCE_COLOR: 1
       shell: bash
@@ -354,4 +388,5 @@ runs:
             --model "$CODEX_MODEL" \
             --effort "$CODEX_EFFORT" \
             --safety-strategy "$CODEX_SAFETY_STRATEGY" \
-            --codex-user "$CODEX_USER"
+            --codex-user "$CODEX_USER" \
+            --project-instructions-mode "$CODEX_PROJECT_INSTRUCTIONS_MODE"