Make Codex HUMAN_GATE launcher compatible with current CLI and end-to-end Git delivery

[dapi]

Context

Follow-up to #26.

start-issue v1.13.2 builds the HUMAN_GATE command in scripts/lib/start_issue/agent.sh as:

codex exec \
  [--model "$MODEL"] \
  --cd "$WORKTREE_PATH" \
  --ask-for-approval never \
  --sandbox workspace-write \
  --json \
  --output-last-message "$STATE_DIR/last-message.txt" \
  -

This launcher no longer provides a reliable path to STATUS: DONE for issue workflows that include normal GitHub delivery.

Problems

1. Current Codex CLI rejects the generated argument order

With codex-cli 0.144.6:

error: unexpected argument --ask-for-approval found

--ask-for-approval is currently a top-level option, so the accepted form is approximately:

codex --ask-for-approval never exec ...

The generated HUMAN_GATE command should be verified against the supported Codex CLI version instead of assuming the older option layout.

2. workspace-write plus never is insufficient for end-to-end delivery

Even after correcting the argument order, the hard-coded permission combination has two relevant boundaries:

• workspace-write has network access disabled by default. The agent cannot read issue comments or linked sources, inspect remote CI, push, or create a PR unless network is separately enabled.
• Codex protects .git and a worktree resolved gitdir in the workspace-write sandbox. With approval policy never, the batch session has no escalation path for commit/ref writes.

A repository can enable shell network access with:

[sandbox_workspace_write]
network_access = true

That allows authenticated gh operations, but it does not remove the protected .git boundary. The result is that an otherwise clear delivery can edit and test files yet still fail or produce a spurious STATUS: HUMAN_GATE before commit, push, and PR creation.

Reproduction

Environment:

• start-issue v1.13.2
• codex-cli 0.144.6
• macOS

Steps:

1. Run start-issue 123 --agent codex --human-gate --dry-run and inspect the generated command.
2. Run the generated codex exec ... --ask-for-approval never ... form with Codex 0.144.6; it is rejected before prompt execution.
3. Move the approval option before exec and run with --sandbox workspace-write in a repository without explicit network access; GitHub reads/actions are unavailable.
4. Enable sandbox_workspace_write.network_access = true; authenticated gh works, but the sandbox still does not provide the Git metadata writes required by the delivery contract.

Expected behavior

HUMAN_GATE mode should have an explicit, documented permission contract that matches its advertised workflow:

• the generated command is valid for supported Codex CLI versions;
• the agent can read the complete GitHub issue context, including comments and linked sources;
• a normal successful run can edit, test, commit, push, and create/update a PR;
• genuine product, security, production, or approval decisions still return STATUS: HUMAN_GATE;
• missing capabilities fail early with a precise diagnostic rather than being reported as a task-level Human Gate.

The implementation could use a configurable Codex permission/profile mechanism rather than hard-coding one policy. The exact safe default is a design decision, but the mode should distinguish working-tree-only automation from full Git delivery.

Acceptance criteria

• HUMAN_GATE command construction is compatible with the supported Codex CLI version and covered by tests.
• The permission model for network and Git metadata writes is explicit and documented.
• A documented full-delivery configuration can complete edit, test, commit, push, and PR creation without an artificial Human Gate.
• A restricted configuration either stops before delivery with a capability diagnostic or has a correspondingly restricted completion contract.
• Tests cover command option placement and configured permission/profile propagation.
• Dedicated HUMAN_GATE help explains required GitHub authentication, network access, Git write access, and troubleshooting.