claude-agmsg-delegate

# claude-agmsg-delegate

Purpose: Codex Skill for bounded, headless review and opt-in Sonnet Git-workspace implementation through agmsg, restricted to a verified paid Claude.ai subscription.

Repository: https://github.com/MaururuTakumi/claude-agmsg-delegate
License: MIT
Runtime dependencies: Python 3.9+, Codex, Claude Code, agmsg
Python package dependencies: none

AI install sequence:
1. Read AGENTS.md, README.md, SKILL.md.
2. Run: make test
3. Run: ./install.sh --dry-run
4. Install the offline Skill with `./install.sh` before resolving runtime dependencies. Missing Claude or agmsg must not leave it uninstalled.
5. Change to the target project where delegation will be used and run the installed `delegate_claude.py doctor`; never join the temporary Skill clone merely to pass verification. Doctor is non-mutating and requires Claude Code 2.1.169+ with `--safe-mode` before checking subscription auth and agmsg. Official agmsg 1.1.8+ includes local read-only `api.sh`; a legacy `list-ids.sh` installation is accepted but never required.
6. If agmsg is missing or outdated, stop and get explicit approval before `npx agmsg`, team join, or delivery-mode setup. After approval, use only `whoami.sh`, `join.sh`, and `delivery.sh` from the target project. With no existing team, propose `<target-project-name>-team / codex` and wait for confirmation. Offer only `1) turn` (recommended; Enter means turn) or `2) off`; never select `monitor` or `both`. Never silently create or edit agmsg files directly.
7. Restart Codex and start a new task so the pre-update Skill cannot remain cached.
8. Verify `delegate_claude.py --version` is `0.4.2`, then run delegate_claude.py run --model fable --task "Installation verification only." --dry-run and require `contract_version=3`.
9. Doctor and dry-run may execute local read-only `claude auth status --json`, but must not send agmsg or invoke a model.

Safety invariants:
- Codex owns orchestration, diff review, commands, tests, integration, and final decisions.
- Fable is hard read-only with any role. Advisory Sonnet may use only `Read,Glob,Grep` with `--permission-mode plan` in the target project directory. Only `--model sonnet --role implementer --workspace-write` enables file edits with `Read,Edit,Write,Glob,Grep` and `--permission-mode acceptEdits`; these jobs require a Git worktree and return `review_required=true`. Bash remains unavailable.
- The obsolete 0.1 no-tools rule must not override runtime contract 3. Completed jobs require observed Read events, `workspace_grounded=true`, and project-relative `files_read`.
- Codex reviews before/after status and diff and runs tests after every workspace-write job.
- No Claude UI, tmux pane, existing session, daemon, or monitor is required.
- Default agmsg mailboxes are `codex-delegate` and `claude-delegate`, isolated from visible Ghostty/Gdash loops.
- Require `claude.ai` + `firstParty` + a paid subscription before send and immediately before inference.
- Reject API keys, auth tokens, custom base URLs, API-key helpers, and cloud-provider routes; never fall back.
- Pass only a minimal environment allowlist and use `--safe-mode --setting-sources ""`.
- Fail closed with `CLAUDE_SAFE_MODE_UNAVAILABLE` before authentication, agmsg send, or model inference when the selected Claude CLI lacks `--safe-mode`; never silently omit it.
- Recheck auth after inference and discard output if it changed.
- Account-level Extra usage / usage credits is a separate setting and must be off for zero variable charges.
- No permission bypass.
- No direct agmsg DB/team/config access.
- No automatic role/hook changes.
- No automatic `npx agmsg`, team join, or delivery-mode selection.
- No agmsg `monitor` or `both` mode for this Codex workflow.
- No secrets or raw large logs.
- job_id correlates every request and response.
- timeout returns running with worker stage/elapsed evidence; collect is idempotent and detects dead workers.

Primary files:
- README.md: human install and usage guide
- AGENTS.md: mandatory coding-agent instructions
- SKILL.md: Codex Skill behavior
- scripts/delegate_claude.py: deterministic wrapper
- tests/test_delegate_claude.py: no-network fixture E2E
- install.sh: non-destructive installer with dry-run, backups outside skills/, and legacy-backup quarantine