# Codex Plugin Workflows Policy

最終更新: 2026-05-15

Codex plugin / workflow 連携と、Claude Code native `/goal` (2.1.139+) を Harness で扱う時の運用方針。

## ひとことで

Harness の SSOT は `Plans.md`。
Codex 側の `/goal` も、Claude Code native の `/goal` も、workflow state は補助入力として扱い、同じ計画を二重管理しない。

## たとえると

`Plans.md` はチームのホワイトボード。
`/goal` はその場のメモ。
メモは便利だが、ホワイトボードと食い違ったら、どちらを見ればよいか分からなくなる。

## `/goal` と `Plans.md` (Codex `/goal` + CC native `/goal` 共通)

CC 2.1.139 で Claude Code native `/goal` が追加された。Codex `/goal` と CC native `/goal` は
**どちらも session continuation memo** として扱う。Plans.md は唯一の task SSOT のままにする。

| 項目 | 方針 |
|------|------|
| 長期タスク管理 | `Plans.md` を正本にする |
| Codex `/goal` | 現在 turn / current run の補助メモとして扱う |
| CC native `/goal` (2.1.139+) | 同じく現在 turn / current run の補助メモとして扱う |
| task status | `Plans.md` の `cc:TODO` / `cc:WIP` / `cc:完了` を優先 |
| conflict | `Plans.md` を読み、必要なら `/goal` 側を更新する |

禁止:

- `/goal` (Codex or CC) にだけ acceptance criteria を置く
- `Plans.md` と `/goal` に別々の task list を持つ
- worker が `Plans.md` を読まずに `/goal` だけで完了判断する
- CC native `/goal` 完了条件を Plans.md DoD と差し替える

### CC native `/goal` の使ってよいケース

- 「次の 1 turn だけ集中したい sub-goal」を一時的に表示する
- `--print` / `-p` モードで完了条件を 1 ターン分だけ宣言する
- Remote Control 越しに operator が hand-off メモを残す

### CC native `/goal` で禁止のケース

- Plans.md `cc:WIP` の task を `/goal` 側で「完了」に書き換える
- Plans.md と独立した DoD を `/goal` だけに残す
- `/goal` の completion condition が Plans.md acceptance criteria と矛盾する状態で turn を継続する

## Codex `0.130.0` stable workflow updates

Codex `0.130.0` stable (`rust-v0.130.0`, published `2026-05-08T23:09:55Z`) で増えた workflow surface は、Harness では「便利になった観測・接続手段」として扱う。
`Plans.md` 正本、primary environment write guard、hook opt-in の境界は緩めない。

| 項目 | Codex `0.130.0` の変更 | Harness 判断 |
|------|-------------------------|--------------|
| `codex remote-control` | headless remotely controllable app-server の simpler top-level entrypoint | 明示起動する診断・操作 surface として案内する。配布 config では remote-control default を持たない |
| App-server thread pagination | app-server clients can page large threads | 長い Breezing / loop transcript は page して読む。1 回で全 transcript を読み込む前提にしない |
| `view_image` selected environment resolution | multi-environment session で selected environment 経由の file 解決ができる | screenshot / artifact evidence には environment と workdir を添える。non-primary environment の artifact を primary repo の証拠と混同しない |
| Live app-server config refresh | live app-server threads pick up config changes without restart | 設定反映確認には使うが、Harness setup は「再起動不要」を秘密値更新や権限変更の雑な運用理由にしない |
| Turn diff accuracy | `apply_patch` partial failure を含めて turn diffs が正確になった | turn diff は review 補助として使う。ただし最終判定は `git diff`、tests、package checks で行う |
| Plugin details bundled hooks | plugin details now show bundled hooks | plugin install / share 前に bundled hooks を確認する。Harness bundled hooks は opt-in 原則を維持する |
| Plugin sharing metadata | plugin sharing exposes link metadata and discoverability controls | link metadata と discoverability controls を公開範囲の一部として扱う。既定で過度に discoverable にしない |
| Configurable OTel trace metadata | configurable OpenTelemetry trace metadata | trace metadata は debugging / triage の補助。customer data や secret を入れない |
| Built-in MCPs as runtime servers | built-in MCPs first-class runtime servers | built-in MCP と plugin-provided MCP を混同しない。所有者と設定源を report に残す |
| `CODEX_HOME` environments TOML provider | `CODEX_HOME` 配下の environment provider を扱える | user-level environment と repo-local config の優先順位を明示し、write は primary environment に固定する |
| Skill root cleanup | remove skills list extra roots | 余分な skills root を前提にした fallback を増やさない。Harness は明示 mirror / path-based loading を維持する |

## Remote-control / app-server operations

`codex remote-control` は、headless app-server を遠隔操作しやすくする入口です。
Harness では次の扱いに固定する。

- 起動は user / operator が明示する。`codex/.codex/config.toml` には remote-control defaults を入れない。
- port、pid、auth boundary、selected environment、workdir を確認してから操作する。
- app-server clients が large threads を扱う時は pagination を使い、必要な page と timestamp を report に残す。
- live app-server threads が config changes を拾える場合でも、secret、network、provider、hook policy の変更は repo / user config の diff として残す。
- stale artifact を見つけても、担当外の environment なら勝手に削除しない。

## Telemetry / MCP / environment setup surfaces

Codex `0.130.0` は configurable OpenTelemetry trace metadata、built-in MCPs first-class runtime servers、`CODEX_HOME` environments TOML provider も含む。
Harness はこれらを便利な setup surface として扱うが、所有者境界を曖昧にしない。

- OpenTelemetry trace metadata には user / customer data、API key、provider credential、private URL を入れない。debugging / triage に必要な low-cardinality metadata だけを使う。
- built-in MCPs は Codex runtime の owned surface。plugin-provided MCP と同じ名前・同じ責務にしない。
- `CODEX_HOME` environments TOML provider は user-level environment source として扱う。repo-local `.codex/config.toml` や managed requirements と衝突する時は、実際に選択された environment を report する。
- remove skills list extra roots により、暗黙の extra root fallback に頼る運用は弱くなる。Harness は `scripts/setup-codex.sh` による user install、または `[[skills.config]]` path-based loading のどちらかを明示する。
- write turn は引き続き one primary environment。environment provider が増えても、複数 environment へ同時に書かない。

## Plugin-bundled hooks

Codex `0.128.0` の plugin-bundled hooks は、Harness では opt-in の workflow extension として扱う。
Codex `0.130.0` では plugin details に bundled hooks が表示されるため、install / share 前の確認項目として明示的に見る。

Plugin に hooks を同梱する場合、既定で project の挙動を強く変えない。

CCH の Codex manifest は inline の空 hook object を明示する。これは
Codex が plugin root の Claude 向け `hooks/hooks.json` へ fallback し、未対応の
agent / async handler を警告することを防ぐためである。Codex の project hook は
`harness gen hooks` が `.codex/hooks.json` へ別途生成し、vendor schema に含まれない
監査 metadata はその JSON に埋め込まない。

方針:

- hook は opt-in にする
- 破壊的操作、push、deploy、外部送信は既定無効
- `PostToolUse` で output を改変する場合は `docs/output-governance.md` に従う
- hook の stdout は JSON contract を守る
- plugin details に表示される bundled hooks と、実際に配布する hooks の差分を残さない

なぜ:

plugin を入れただけで hook が勝手に強く動くと、user / project の権限境界が見えにくくなるため。

## Plugin sharing metadata and discoverability

Codex `0.130.0` では plugin sharing に link metadata と discoverability controls が出る。
Harness の plugin 配布では、共有 URL そのものだけでなく、誰に見つかるか、何の説明で表示されるかを release surface として扱う。

方針:

- link metadata は plugin 名、用途、危険な hook / external-send の有無が分かる形にする。
- discoverability controls は明示的に選ぶ。内部検証中の plugin を公開 discoverable にしない。
- shared link を貼る時は、対象 version と install 後の verification command を併記する。
- plugin details で bundled hooks を確認してから share する。

## External agent import ownership

外部 agent を import する時は、所有者を明確にする。

| ケース | 所有者 | 方針 |
|--------|--------|------|
| Harness 配布 agent | Harness | repo 内で review / test / sync 対象 |
| user local agent | User | Harness は上書きしない |
| third-party plugin agent | Third-party plugin | Harness は依存関係として扱い、内容を fork しない |
| copied external agent | Harness fork | fork 元、変更理由、更新責任を docs に残す |

禁止:

- 外部 agent を黙って Harness 配布物に混ぜる
- user local agent を setup で上書きする
- fork 元の policy / license / update path を記録せずに改変する

## MultiAgentV2 and `agents.max_threads = 8`

`agents.max_threads = 8` は強い並列実行の上限として扱う。
常に 8 並列で走らせるという意味ではない。

方針:

- default は task size と risk に応じて少なめに始める
- IO-bound な調査は並列度を上げてよい
- 同じファイルを触る worker は並列にしない
- write-heavy work は ownership file list を先に固定する
- 8 は上限。review / integration / final verification は直列に戻す

例:

| 作業 | 推奨 |
|------|------|
| docs grep / evidence collection | 4-8 threads |
| 独立した docs 章の作成 | 2-4 threads |
| 同じ TypeScript module の修正 | 1-2 threads |
| release / version sync | 1 thread |

## Sticky environments

Sticky environment は、同じ作業環境を再利用して setup cost を下げる仕組みとして扱う。
ただし、古い server / cache / artifact が残るリスクがある。

safe default:

- one primary environment per write turn を維持する
- remote / sticky environment は read-only first で確認し、書き込み前に primary environment を明示する
- task 開始時に `git status --short` を確認する
- app server の port / pid / health を確認する
- env var と secret をログに出さない
- stale artifact を見つけても、担当外なら勝手に削除しない

## App-server artifacts

app server が生成する artifact は、review / reproduction に役立つ一方で、古くなると誤判定の原因になる。

方針:

- screenshot、trace、coverage、test output は path と生成時刻を報告する
- artifact を根拠にする時は、再生成コマンドも残す
- stale artifact を cleanup する時は、対象 path を明示する
- production credential や customer data を artifact に含めない

## Codex cloud / local boundary

Codex cloud task は sandboxed environment で動く。
Harness repo 内の local `Plans.md` と cloud 側の task state は自動同期される前提にしない。

そのため:

- cloud task の成果は PR / diff / report として受け取る
- Harness の完了判定は local repo で `git diff`、tests、`Plans.md` を確認して行う
- cloud artifact をそのまま source of truth にしない

## Sources

- OpenAI Codex docs: https://platform.openai.com/docs/codex