@cardor/agent-harness-kit 2.1.1 → 2.3.0

package/README.md

@@ -196,7 +196,11 @@ Interactive scaffold. Asks for your project name, description, AI provider, docs
 
 Claude Code only, init asks you to pick a model for each of the 5 core roles (lead, explorer, consultant, builder, reviewer) one at a time: `inherit` (default), `haiku`, `sonnet`, `opus`, or `fable`. Each choice is written straight into that role's generated `.claude/agents/<role>.md` frontmatter as a `model:` line at scaffold time — it is never persisted to the config file. Picking `inherit` (the default) emits no `model:` line at all, leaving Claude Code to apply its own default. Agent files are user-owned once generated (see [Agent files are yours](#agent-files-are-yours) below), so after init the model can be changed three ways: hand-editing the `model:` frontmatter line directly, running [`ahk models`](#ahk-models) to re-prompt and regenerate just the 5 agent files, or running `ahk build --force` (which re-prompts too, then regenerates everything `--force` regenerates).
 
-OpenCode, Codex CLI, and Grok Build are unaffected by this prompt — it never appears for those providers. OpenCode and Grok Build have no closed model enum to prompt against, and Codex's model is still set by hand-editing `model = "..."` in its TOML.
+Codex CLI only, init asks you to pick a **model and a reasoning effort** for each of the 5 core roles, one role at a time: model choices are `gpt-5.6-sol`, `gpt-5.6-terra` (default), `gpt-5.6-luna`, `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.3-codex-spark`; effort choices are `minimal`, `low`, `medium` (default), `high`, `xhigh`. Not every model supports every effort level — Codex applies its own per-model behavior for an unsupported combination, so pick deliberately rather than assuming universal compatibility. Both choices are written straight into that role's generated `.codex/agents/<role>.toml` as `model = "..."` / `model_reasoning_effort = "..."` lines at scaffold time — never persisted to config.toml. Agent files are user-owned once generated, so after init the model/effort can only be changed by hand-editing the TOML directly (there is no Codex equivalent of `ahk models` yet) or running `ahk build --force` (which re-prompts, then regenerates everything `--force` regenerates).
+
+Separately, `.codex/config.toml` always gets a project-wide top-level default — `model = "gpt-5.6-terra"` and `model_reasoning_effort = "medium"` — written once and preserved across every subsequent `ahk build`/`ahk init --force`: if you hand-edit either value in config.toml, your edit is never overwritten. Per-role `model`/`model_reasoning_effort` lines in `.codex/agents/<role>.toml` (above) act as overrides of this baseline for that one role.
+
+OpenCode and Grok Build are unaffected by either prompt — it never appears for those providers, since neither has a closed model enum to prompt against.
 
 **Storage scope** — where the harness DB (and its `current.md` fallback) physically lives:
 
@@ -268,7 +272,7 @@ ahk build --force
 - **It discards your customizations.** Every agent file is rewritten from the template. Prompt edits, `model:` lines, and restriction tweaks are all lost.
 - **It backs up first.** Before overwriting anything, the current content of every affected file is copied under `.harness/backups/` — agent files to `agents-<timestamp>/`, hand-edited `AGENTS.md`/`CLAUDE.md` to `derived-<timestamp>/`. If that backup cannot be written, the command aborts and **no file is modified** — the same fail-safe as [`ahk migrate storage --force`](#storage-migration).
 - **It names what it touched.** The command prints every file it overwrote and the backup location, so you can diff or restore.
-- **Claude Code only, it also re-prompts for models.** Before regenerating, `ahk build --force` runs the same per-role model prompt as `ahk init` (see above) and injects the fresh choices into the regenerated frontmatter. Other providers are unaffected — no prompt appears for them.
+- **Claude Code and Codex CLI also re-prompt for models.** Before regenerating, `ahk build --force` runs the same per-role prompt as `ahk init` for the current provider — the model prompt on Claude Code, or the model **and** reasoning-effort prompt on Codex CLI (see above) — and injects the fresh choices into the regenerated frontmatter/TOML. OpenCode and Grok Build are unaffected — no prompt appears for them, since neither has a closed model enum to prompt against.
 
 `--force` also regenerates a hand-edited `AGENTS.md` or `CLAUDE.md` (backing it up first) — the only time you need it for those files, since an *unedited* one already re-generates on its own when config changes.
 
@@ -467,6 +471,8 @@ ahk migrate provider --to grok-cli
 ahk migrate --to opencode
 ```
 
+Migrating always regenerates the target provider's agent files from scratch, so — same as `ahk init` and `ahk build --force` — it also runs that target's per-role prompt first, before anything is written: the model prompt when migrating **to** Claude Code, or the model **and** reasoning-effort prompt when migrating **to** Codex CLI (see [`ahk init`](#ahk-init) above for what each prompt asks). Migrating to OpenCode or Grok CLI shows no prompt at all, since neither has a closed model enum to prompt against.
+
 #### `ahk migrate storage` — ⚠️ sensitive, reads/writes real harness data
 
 Migrates the harness database between storage backends: **local↔global scope** (moving `.harness/harness.db` in/out of `~/.harness/dbs/<projectId>/`) and **sqlite↔postgres/mysql** (dumping and reloading all 6 tables — tasks, task_acceptance, actions, action_sections, action_files, action_tools — inside a single transaction). It is **not interactive** — `agent-harness-kit.config.ts` (`storage.scope`, `storage.sqlitePath` (local scope only), `database.type`/`connectionString`) is the only source of truth for the desired target, compared against the real current state recorded in `.harness/storage-state.json`.
@@ -810,7 +816,7 @@ For the **builder**, which has no restrictions, the key is omitted entirely —
 
 ```toml
 name = "builder"
-sandbox_mode = "workspace-write"
+sandbox_mode = "danger-full-access"
 
 description = """
 Builder agent — implements the plan produced by explorer and lead.
@@ -827,7 +833,9 @@ You are the builder agent for MyApp. Follow these rules:
 """
 ```
 
-Codex CLI has no per-agent tool denylist, so `sandbox_mode` is the only real mechanism: `"read-only"` for lead, explorer, consultant, and reviewer; `"workspace-write"` for builder. Because Codex keeps the write tools *visible* to the model even under a read-only sandbox, the restriction is additionally restated in prose inside `developer_instructions` — without it the model burns turns on calls the sandbox will reject.
+**Deliberate security tradeoff (all 5 roles, not just builder).** Codex CLI has no per-agent tool denylist. Earlier versions of this project used `sandbox_mode` as the OS-level enforcement mechanism (`"read-only"` for lead/explorer/consultant/reviewer, `"workspace-write"` for builder). As of a deliberate, user-chosen configuration decision (task #83), **every role now runs with `sandbox_mode = "danger-full-access"`** — i.e. fully unsandboxed, with no OS-level write protection at all, for lead, explorer, consultant, builder, and reviewer alike.
+
+This means the no-write restriction for lead/explorer/consultant/reviewer under Codex CLI is enforced **entirely by prompt instruction**, not by the operating system. Nothing technically blocks or rejects a write from a "read-only" role under Codex anymore — the restriction is restated in prose inside `developer_instructions` (see `CODEX_READ_ONLY_NOTICE` in `src/core/materializer/agent-restrictions.ts`), and that prose is the *only* thing standing between a no-write role and it actually writing files. A violation won't fail loudly; it will silently corrupt the harness's audit trail and workflow guarantees. This tradeoff was explained to and knowingly chosen by the project's maintainer — it is not an oversight, and it is not a general recommendation. If you fork this project, you may want to reintroduce `"read-only"`/`"workspace-write"` for stronger guarantees under Codex.
 
 **Grok Build** (`.grok/agents/*.md`) uses markdown + YAML frontmatter, like Claude Code and OpenCode — but its `tools:` field is an **allowlist**, the inverse shape of Claude's `disallowedTools`. A restricted role must enumerate every tool it IS allowed to use, since there is no way to say "everything except Write/Edit":
 
@@ -920,7 +928,7 @@ The harness exposes these tools via MCP. Agents use them instead of reading file
 | **builder**    | Implements the plan. The only role that writes — its write tools are enabled where every other role's are disabled. Records every file modified. |
 | **reviewer**   | Verifies all acceptance criteria are met. Approves or blocks. Runs health check before approving.                                           |
 
-> **Scope note.** What a role may not do is enforced **per tool, not per path**. There is no per-agent path scoping and it is not configurable: the `allowedPaths` / `writablePaths` fields were removed because they were only interpolated into prompt text and no provider ever enforced them — they looked like a security control without being one. The real restriction lives in `src/core/materializer/agent-restrictions.ts`, which each provider translates natively: `disallowedTools` in Claude Code, `permission.edit` in OpenCode, `sandbox_mode` in Codex CLI, and a `tools:` allowlist in Grok Build. If a config still declares the removed fields they are stripped at load time with a warning.
+> **Scope note.** What a role may not do is enforced **per tool, not per path**. There is no per-agent path scoping and it is not configurable: the `allowedPaths` / `writablePaths` fields were removed because they were only interpolated into prompt text and no provider ever enforced them — they looked like a security control without being one. The restriction lives in `src/core/materializer/agent-restrictions.ts`, which each provider translates natively: `disallowedTools` in Claude Code, `permission.edit` in OpenCode, `sandbox_mode` in Codex CLI, and a `tools:` allowlist in Grok Build. If a config still declares the removed fields they are stripped at load time with a warning. **Codex CLI is the one exception to "enforced":** by deliberate project configuration all 5 roles run with `sandbox_mode = "danger-full-access"` (see below), so under Codex specifically the restriction is enforced by prompt instruction only, not by the OS.
 >
 > **The entire `agents` config key has since been removed too**, for the same underlying reason: everything left in it was either dead or better expressed elsewhere. `instructionsPath`, `context` and `custom` were written by the generator and never read by anything; `model` was the only field with an effect, and it now belongs in the agent file's frontmatter alongside the role prompt, since that file is user-owned. A config that still declares `agents` loads normally — the key is ignored, with one aggregated warning pointing at the agent file.
 >
@@ -1080,7 +1088,7 @@ See [SECURITY.md](./SECURITY.md) for the vulnerability reporting process, suppor
 - ✅ **`tasks.add` via MCP** — agents can create new tasks on the fly without leaving the conversation.
 - ✅ **Global installation** — `ahk init` can install the harness to your home directory, shared across projects.
 - ✅ **Input validation** — all CLI prompts validate and retry on bad values.
-- ✅ **Codex CLI provider** — full support for OpenAI Codex CLI. Generates `.codex/agents/*.toml` files with proper `sandbox_mode` per role and merges `.codex/config.toml` for MCP registration. Overrides the built-in `default` agent so the harness lead runs by default.
+- ✅ **Codex CLI provider** — full support for OpenAI Codex CLI. Generates `.codex/agents/*.toml` files (`sandbox_mode = "danger-full-access"` for all roles, by deliberate project configuration — see the Scope note above) and merges `.codex/config.toml` for MCP registration. Overrides the built-in `default` agent so the harness lead runs by default.
 - ✅ **Grok Build provider** — full support for xAI's Grok Build. Generates `.grok/agents/*.md` files with a `tools:` allowlist per role and merges `.grok/config.toml` for MCP registration.
 - **Graphify integration** — connect the harness to Graphify to visualize agent workflows, task dependencies, and action timelines as interactive graphs.
 - **Open Telemetry integration** — emit OpenTelemetry spans for all agent actions, file operations, and tool calls.