@cardor/agent-harness-kit 2.1.0 → 2.2.0

package/README.md

@@ -34,6 +34,7 @@ npx ahk init
   - [Commands](#commands)
     - [`ahk init`](#ahk-init)
     - [`ahk build`](#ahk-build)
+    - [`ahk models`](#ahk-models)
     - [`ahk dashboard`](#ahk-dashboard)
     - [`ahk status`](#ahk-status)
     - [`ahk health`](#ahk-health)
@@ -179,9 +180,9 @@ npx ahk init
 
 Detection order: the `packageManager` field in your `package.json` (e.g. `"packageManager": "pnpm@8.15.0"`) takes priority when present; otherwise `ahk` falls back to lockfile heuristics; if nothing is detected, it defaults to npm.
 
-**Global installs bypass the package manager entirely.** Every command in the table above asks your package manager to resolve a *locally installed* `ahk` binary — `npx --no` deliberately refuses to download one, and `pnpm exec`/`yarn run`/`bunx --no-install` have nothing to point at. If you installed the CLI globally and never added it to the project, all five of those commands fail. So `ahk` checks for the local install first (the same check that decides your config file format, above) and, when there is none, generates the bare `ahk serve --port <port>` — resolved from your `PATH` like any other global binary. The package-manager-specific commands are used only when a local install actually exists. If, on that global-install path, `ahk` is not resolvable on your `PATH` at generation time, `ahk` prints a non-blocking warning (the command still succeeds) pointing you at `npm i -g @cardor/agent-harness-kit` or a local install — moving the "binary not found" failure earlier instead of surfacing it later when the MCP server is spawned.
+**Global installs bypass the package manager entirely.** Every command in the table above asks your package manager to resolve a *locally installed* `ahk` binary — `npx --no` deliberately refuses to download one, and `pnpm exec`/`yarn run`/`bunx --no-install` have nothing to point at. If you installed the CLI globally and never added it to the project, all five of those commands fail. So `ahk` checks for a *real* local install first and, when there is none, generates the bare `ahk serve --port <port>` — resolved from your `PATH` like any other global binary. The package-manager-specific commands are used only when a local install actually exists. If, on that global-install path, `ahk` is not resolvable on your `PATH` at generation time, `ahk` prints a non-blocking warning (the command still succeeds) pointing you at `npm i -g @cardor/agent-harness-kit` or a local install — moving the "binary not found" failure earlier instead of surfacing it later when the MCP server is spawned.
 
-Working inside the `agent-harness-kit` repository itself counts as a local install: the package manager can resolve the workspace binary, so the `pnpm exec` form is generated rather than the bare one.
+Working inside the `agent-harness-kit` repository itself does **not** count as a local install for this decision: there is no real `node_modules/@cardor/agent-harness-kit` entry for a package manager to resolve, so self-dev generates the bare global `ahk serve --port <port>` form, same as any other project with no local install. This is a narrower check than the one deciding your config file format, above (`ahk init`'s `.ts`/`.mjs`/`.cjs` vs. `.json` choice) — that check still treats self-dev as satisfied, since it only cares whether the package is resolvable for type-checking purposes, not whether a package manager can mediate a spawned command.
 
 **Existing projects:** if you initialized your project before this change, your `.mcp.json`/`opencode.json`/`.codex/config.toml`/`.grok/config.toml` may still have a hardcoded `npx` command. No migration step is needed — `ahk build` always regenerates (merges) these files from scratch on every run, so the command self-corrects the next time you run `ahk build` (or `ahk build --sync`), including if you've since switched package managers.
 
@@ -193,9 +194,13 @@ Working inside the `agent-harness-kit` repository itself counts as a local insta
 
 Interactive scaffold. Asks for your project name, description, AI provider, docs path, storage scope, task adapter, and an optional first task. Creates all harness files in the current directory.
 
-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. This prompt only runs during `ahk init`'s one-time scaffold, not on `ahk build` — agent files are user-owned once generated (see [Agent files are yours](#agent-files-are-yours) below), so after init the model is changed the same way as any other edit: hand-editing the `model:` frontmatter line directly.
+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:
 
@@ -267,6 +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.
 
 `--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.
 
@@ -276,6 +282,21 @@ ahk build --force
 
 ---
 
+### `ahk models`
+
+Claude Code only. Re-runs `ahk init`'s per-role model prompt and regenerates ONLY the 5 `.claude/agents/*.md` files with the chosen models — nothing else (not `AGENTS.md`, `CLAUDE.md`, `.mcp.json`, `.claude/settings.json`, your config file, docs path, storage scope, or task adapter).
+
+```bash
+ahk models
+```
+
+- Prompts once per role (lead, explorer, consultant, builder, reviewer): `inherit` (default), `haiku`, `sonnet`, `opus`, or `fable` — same prompt as `ahk init`.
+- Always regenerates all 5 agent files, backing up the previous content first under `.harness/backups/agents-<timestamp>/` — the same fail-safe [`--force`](#--force) uses.
+- On a non-Claude-Code project, it prints a one-line no-op message and exits — no prompt.
+- If no `agent-harness-kit.config` is found, it prints a message pointing at `ahk init` and exits — no prompt, no stack trace.
+
+---
+
 ### `ahk dashboard`
 
 Opens a local web dashboard to visualize everything stored in the harness database — tasks, agent actions, file operations, tool usage, and live timelines. Updates in real time via WebSocket as agents work.
@@ -793,7 +814,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.
@@ -810,7 +831,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":
 
@@ -903,7 +926,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.
 >
@@ -1063,7 +1086,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.