Skip to content

Add Codex human-gate delivery permissions #41

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dapi wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Add Codex human-gate delivery permissions #41

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
46579e8
minor
dapi Aug 4, 2026
f783545
Add Codex human-gate delivery permissions
dapi Aug 4, 2026
f3db24b
Address human-gate permission review
dapi Aug 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 46 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,7 @@ second runtime implementation.
| `--prompt-file PATH` | Prompt template file for the selected agent. With `init`, the file content to write. Mutually exclusive with `--prompt`. |
| `--improve-prompt` | Ask the selected agent to generate a reviewable improved prompt template proposal, then exit before creating a worktree. |
| `--human-gate` | Codex-only batch mode for issue work. Runs `codex exec`, exits on `STATUS: DONE`, and resumes the same session on `STATUS: HUMAN_GATE`. |
| `--human-gate-permissions restricted\|full-delivery` | Select the human-gate capability contract. Requires `--human-gate`; CLI overrides `START_ISSUE_HUMAN_GATE_PERMISSIONS`; default is `restricted`. |
| `--human-gate-help` | Show dedicated help for the Codex human-gate workflow, including prompt contract, exit codes, and state files. |
| `--prompt-output-file PATH` | Proposal output path for `--improve-prompt`. |
| `--no-init` | Do not run `init.sh` even if it exists in the created worktree. |
Expand Down Expand Up @@ -182,6 +183,7 @@ Related Claude Code marketplace workflows:
| `START_ISSUE_PROMPT` | Inline prompt template used when no CLI prompt is provided. It overrides project and user prompt files. Mutually exclusive with `START_ISSUE_PROMPT_FILE` when no CLI prompt is provided. |
| `START_ISSUE_PROMPT_FILE` | Prompt template file used when no CLI prompt is provided. It overrides project and user prompt files. Mutually exclusive with `START_ISSUE_PROMPT` when no CLI prompt is provided. |
| `START_ISSUE_WORKTREE_DIR` | Default parent directory for created worktrees when `--worktree-dir` is not provided. Built-in default: `~/worktrees`. |
| `START_ISSUE_HUMAN_GATE_PERMISSIONS` | Human-gate capability contract when the CLI option is absent: `restricted` or `full-delivery`. Built-in default: `restricted`. |
| `START_ISSUE_DUMP_PROMPT` | When set to `1`, dry-run output includes the full rendered prompt instead of only summary information. |

## Configuration Files
Expand Down Expand Up @@ -230,6 +232,35 @@ The batch flow:

This mode is intentionally Codex-only. `--human-gate` with any other agent fails clearly instead of being ignored.

Human-gate permissions are explicit:

- `restricted` is the default. It uses `--sandbox workspace-write` and supports
working-tree edits, but network access, Git metadata writes, push, and PR
delivery are not guaranteed.
- `full-delivery` is an explicit opt-in. It runs Codex with
`--dangerously-bypass-approvals-and-sandbox`, allowing the normal issue
workflow to read GitHub context, edit, test, commit, push, and create or
update a PR when the current `gh` session and repository permissions allow
it. This is unsandboxed execution.

Select the mode with the CLI (highest precedence), the environment, or the
safe built-in default:

```bash
start-issue 123 --agent codex --human-gate \
--human-gate-permissions full-delivery

START_ISSUE_HUMAN_GATE_PERMISSIONS=full-delivery \
start-issue 123 --agent codex --human-gate
```

Full delivery changes launcher capability only. It does not authorize
destructive Git operations, production/security changes, or product decisions;
the prompt must still return `STATUS: HUMAN_GATE` for those. Before using it,
verify `gh auth status`, the selected account, the remote, and repository write
access. A restricted capability failure should be handled by manual delivery or
an explicit full-delivery rerun, not reported as a task-level product decision.

When the workflow is about to block for a branch/worktree decision, it prints
`Waiting for input: ...`. Before handing control to an interactive agent or
Codex batch run, it prints `Handing off to <agent> in <worktree>`. A non-zero
Expand Down Expand Up @@ -263,7 +294,7 @@ State files:

### Local real-Codex E2E smoke test

The normal Bats suite uses a fake Codex CLI. To exercise the real local Codex
The normal Go test suite uses a fake Codex CLI. To exercise the real local Codex
CLI, run this opt-in test from a `start-issue` checkout:

```bash
Expand All @@ -283,18 +314,29 @@ test/e2e/human-gate.sh --scenario human-gate

Exit the resumed Codex session to let the script verify the artifacts.

To validate actual commit, push, and PR creation in the private fixture, use
the separately authorized unsandboxed scenario. It creates and retains a unique
remote branch, PR, and local diagnostic fixture as evidence:

```bash
START_ISSUE_E2E=1 START_ISSUE_E2E_FULL_DELIVERY=1 \
test/e2e/human-gate.sh --scenario full-delivery
```

#### Scenarios and checks

| Scenario | Command | What it verifies |
| --- | --- | --- |
| `done` | `START_ISSUE_E2E=1 make e2e-human-gate` | A real Codex batch run emits `thread.started`, saves `thread-id`, `events.jsonl`, and `last-message.txt`, ends with `STATUS: DONE`, and leaves no fixture change other than `.start-issue` state. |
| `human-gate` | `START_ISSUE_E2E=1 test/e2e/human-gate.sh --scenario human-gate` | The same artifact and clean-worktree checks, plus the reported explicit `codex resume --include-non-interactive <thread_id>` handoff. The operator exits the resumed interactive session before the script can finish. |
| `full-delivery` | `START_ISSUE_E2E=1 START_ISSUE_E2E_FULL_DELIVERY=1 test/e2e/human-gate.sh --scenario full-delivery` | The current Codex accepts the global full-delivery option and completes a unique fixture commit, push, and PR; the runner prints the retained PR URL and local artifact path. |

Both scenarios verify authenticated `gh`, a real rather than fake Codex binary,
All scenarios verify authenticated `gh`, a real rather than fake Codex binary,
and the required `codex exec` help interface (`--output-last-message`, without
the obsolete `--ask-for-approval` flag). The selected Codex executable is
printed in the test output. They do not prove application behavior beyond this
human-gate protocol and are intentionally excluded from CI.
printed in the test output. The `done` and `human-gate` scenarios do not prove
application behavior beyond this protocol; `full-delivery` additionally proves
the explicitly authorized fixture delivery path. All are excluded from CI.

### CI sandbox E2E

Expand Down
46 changes: 42 additions & 4 deletions README.ru.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,31 @@ Batch flow:

Режим намеренно поддерживается только для Codex. `--human-gate` с любым другим agent завершается явной ошибкой.

Права human-gate задаются явно:

- `restricted` — безопасный default. Он использует `--sandbox workspace-write`
и разрешает редактирование worktree, но не гарантирует network, запись Git
metadata, push и доставку PR.
- `full-delivery` — явный opt-in. Codex запускается с
`--dangerously-bypass-approvals-and-sandbox`, поэтому при корректной `gh`
session и правах репозитория workflow может прочитать GitHub context,
изменить и проверить код, сделать commit/push и создать или обновить PR.
Это unsandboxed execution.

```bash
start-issue 123 --agent codex --human-gate \
--human-gate-permissions full-delivery

START_ISSUE_HUMAN_GATE_PERMISSIONS=full-delivery \
start-issue 123 --agent codex --human-gate
```

Приоритет: CLI, environment, затем `restricted`. Full delivery расширяет только
технические возможности launcher и не разрешает destructive Git operations,
production/security changes или product decisions: для них prompt по-прежнему
обязан вернуть `STATUS: HUMAN_GATE`. Перед запуском проверьте `gh auth status`,
выбранный account, remote и write access к репозиторию.

Перед ожиданием решения по конфликту branch/worktree команда печатает
`Waiting for input: ...`, а перед передачей управления agent —
`Handing off to <agent> in <worktree>`. Ненулевой код `codex exec` считается
Expand Down Expand Up @@ -110,7 +135,7 @@ State files:

### Локальный E2E smoke test с реальным Codex

Обычный Bats-набор использует fake Codex CLI. Для проверки с реальным локальным
Обычный Go test-набор использует fake Codex CLI. Для проверки с реальным локальным
Codex из checkout `start-issue` выполните opt-in команду:

```bash
Expand All @@ -130,18 +155,29 @@ test/e2e/human-gate.sh --scenario human-gate

Выйдите из возобновлённой Codex-сессии, после чего скрипт проверит артефакты.

Для реальной проверки commit, push и создания PR в private fixture используется
отдельно подтверждаемый unsandboxed scenario. Он сохраняет уникальные remote
branch, PR и локальный diagnostic fixture как evidence:

```bash
START_ISSUE_E2E=1 START_ISSUE_E2E_FULL_DELIVERY=1 \
test/e2e/human-gate.sh --scenario full-delivery
```

#### Сценарии и проверки

| Сценарий | Команда | Что проверяется |
| --- | --- | --- |
| `done` | `START_ISSUE_E2E=1 make e2e-human-gate` | Реальный Codex batch run выдаёт `thread.started`, сохраняет `thread-id`, `events.jsonl` и `last-message.txt`, заканчивается `STATUS: DONE` и не меняет fixture worktree за пределами `.start-issue` state. |
| `human-gate` | `START_ISSUE_E2E=1 test/e2e/human-gate.sh --scenario human-gate` | Те же проверки артефактов и чистоты worktree, а также явный handoff `codex resume --include-non-interactive <thread_id>`. Перед завершением скрипта оператор выходит из возобновлённой interactive session. |
| `full-delivery` | `START_ISSUE_E2E=1 START_ISSUE_E2E_FULL_DELIVERY=1 test/e2e/human-gate.sh --scenario full-delivery` | Текущий Codex принимает global full-delivery option и выполняет уникальные fixture commit, push и PR; runner печатает сохранённые PR URL и local artifact path. |

Оба сценария проверяют авторизованный `gh`, реальный, а не fake Codex binary, и
Все сценарии проверяют авторизованный `gh`, реальный, а не fake Codex binary, и
обязательный интерфейс справки `codex exec` (`--output-last-message`, без
устаревшего флага `--ask-for-approval`). Выбранный Codex executable печатается
в test output. Они не доказывают поведение приложения за пределами human-gate
protocol и намеренно не входят в CI.
в test output. `done` и `human-gate` не доказывают поведение приложения за
пределами protocol; `full-delivery` дополнительно проверяет явно разрешённую
доставку в fixture. Все сценарии намеренно не входят в CI.

### CI sandbox E2E

Expand Down Expand Up @@ -253,6 +289,7 @@ boundaries. Новые возможности должны сохранять э
| `--prompt-file PATH` | Файл prompt template для выбранного агента. С `init` - содержимое файла, которое нужно записать. Нельзя использовать вместе с `--prompt`. |
| `--improve-prompt` | Попросить выбранного агента сгенерировать reviewable proposal улучшенного prompt template и выйти до создания worktree. |
| `--human-gate` | Codex-only batch mode для issue workflow. Запускает `codex exec`, выходит на `STATUS: DONE` и резюмирует ту же сессию на `STATUS: HUMAN_GATE`. |
| `--human-gate-permissions restricted\|full-delivery` | Выбрать capability contract human-gate. Требует `--human-gate`; CLI имеет приоритет над `START_ISSUE_HUMAN_GATE_PERMISSIONS`; default — `restricted`. |
| `--human-gate-help` | Показать отдельную справку по Codex human-gate workflow: prompt contract, exit codes и state files. |
| `--prompt-output-file PATH` | Путь для proposal-файла в режиме `--improve-prompt`. |
| `--no-init` | Не запускать `init.sh`, даже если он есть в созданном worktree. |
Expand Down Expand Up @@ -283,6 +320,7 @@ boundaries. Новые возможности должны сохранять э
| `START_ISSUE_PROMPT` | Inline prompt template, который используется, если prompt не задан через CLI. Перебивает project и user prompt files. Нельзя использовать вместе с `START_ISSUE_PROMPT_FILE`, когда prompt не задан через CLI. |
| `START_ISSUE_PROMPT_FILE` | Файл prompt template, который используется, если prompt не задан через CLI. Перебивает project и user prompt files. Нельзя использовать вместе с `START_ISSUE_PROMPT`, когда prompt не задан через CLI. |
| `START_ISSUE_WORKTREE_DIR` | Родительская директория по умолчанию для создаваемых worktree, если `--worktree-dir` не передан. Встроенное значение по умолчанию: `~/worktrees`. |
| `START_ISSUE_HUMAN_GATE_PERMISSIONS` | Capability contract human-gate при отсутствии CLI option: `restricted` или `full-delivery`. Built-in default: `restricted`. |
| `START_ISSUE_DUMP_PROMPT` | Если задана в `1`, dry-run выводит полный rendered prompt вместо краткой информации. |

## Файлы конфигурации
Expand Down
Loading
Loading