Add opt-out for require-task-in-progress gate via env var

.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "agent-utils",
       "description": "Agent infrastructure: skills for multi-agent orchestration + tools for settings drift detection and 2-stage settings merge + rules-sync (SessionStart symlink of plugin rules into the project) + upstream-check (throttled UserPromptSubmit hook that surfaces upstream agent-repo changes and dirty-state nags).",
-      "version": "0.4.1",
+      "version": "0.4.2",
       "author": {
         "name": "Nathan Heaps"
       },
@@ -55,8 +55,8 @@
     },
     {
       "name": "task-utils",
-      "description": "Task discipline hooks (0-or-1 in_progress invariant, write-tool gating, validation-steps + RESULT cites) + manage-tasks skill for atomic-task workflow",
-      "version": "0.1.0",
+      "description": "Task discipline hooks (0-or-1 in_progress invariant, write-tool gating, validation-steps + RESULT cites) + manage-tasks skill + MCP task server fallback for contexts without the built-in Task tools",
+      "version": "0.1.4",
       "author": {
         "name": "Nathan Heaps"
       },
@@ -72,7 +72,8 @@
         "claude-code",
         "agent-discipline",
         "validation-steps",
-        "in-progress-invariant"
+        "in-progress-invariant",
+        "mcp"
       ]
     }
   ]

.claude/plans/post-r6-tasks.md

@@ -0,0 +1,63 @@
+# Post-R6 task breakdown
+
+Date: 2026-05-24
+Branch: `claude/ai-3d-model-generator-XjoUi` (PR [#157](https://github.com/nsheaps/agents/pull/157))
+
+## Context
+
+PR #157 landed phases R1–R6 of the task-utils redesign on this branch (4 commits + an auto-fix lint commit). R7 (in-session validation) was deferred because the new PreToolUse/PostToolUse hooks only load at SessionStart. Several follow-up items came up during the redesign that don't belong in #157 and need their own tracking issues.
+
+This file enumerates those items and the order they should be picked up in. Each item below maps 1:1 to a GitHub issue created in `nsheaps/agents` or `nsheaps/farish`. Issues are chained `Blocked by` so they execute sequentially.
+
+## Items
+
+### 1. R7 — in-session validation of task-utils 0.2.0 redesign — [nsheaps/agents#168](https://github.com/nsheaps/agents/issues/168)
+
+- **Repo**: nsheaps/agents
+- **Blocks**: merge of [#157](https://github.com/nsheaps/agents/pull/157)
+- **What**: With this branch checked out and Claude Code restarted (so new hooks load), verify:
+  1. `task-native-warning.sh` fires `additionalContext` advisory when `TaskCreate` / `TaskUpdate` is used (mode: warn).
+  2. `task-sync-from-legacy.sh` (PostToolUse) copies native Task tool files from `~/.claude/tasks/<sid>/<id>.{json,yaml}` into the project-local flat YAML store and commits them.
+  3. `require-task-in-progress.sh` denies `Write` / `Edit` / `MultiEdit` / `NotebookEdit` when no flat-store task is `in_progress`; allows once an MCP task is `in_progress`.
+  4. `requireTaskInProgress: false` settings opt-out actually disables the gate.
+  5. `mcp__task-utils__task_create` + `mcp__task-utils__task_update(status=in_progress)` round-trips through `git-helper.ts` auto-commit.
+
+### 2. fix: `auto-version-bump` workflow false-positive on `nsheaps/agents` — [nsheaps/agents#169](https://github.com/nsheaps/agents/issues/169)
+
+- **Repo**: nsheaps/agents
+- **Blocked by**: #168
+- **What**: The `auto-version-bump` workflow tries to bump versions that have already been bumped manually in the same PR (e.g. R6 bumped task-utils 0.1.5→0.2.0 manually) and hits a git checkout conflict, failing the run. The workflow should detect "already at target version" and exit cleanly. Confirmed not transient — repros on every push to this branch.
+- **Reference**: failing runs on PR [#157](https://github.com/nsheaps/agents/pull/157).
+
+### 3. chore(task-utils): promote `plugin-settings-lib.sh` to shared-lib plugin — [nsheaps/agents#170](https://github.com/nsheaps/agents/issues/170)
+
+- **Repo**: nsheaps/agents
+- **Blocked by**: #169
+- **What**: R2 introduced an inline `plugin-settings-lib.sh` (3-tier yq-backed config reader) in the task-utils plugin because the agents repo cannot currently depend on ai-mktpl's shared-lib. Once that dependency story is resolved, the inline lib should be deleted and task-utils should source the canonical version from shared-lib.
+- **Prerequisite**: agents repo gains a way to depend on ai-mktpl plugins (out of scope here — track separately if it doesn't already exist).
+
+### 4. chore(tasks): migrate legacy JSON tasks to YAML format — [nsheaps/farish#3](https://github.com/nsheaps/farish/issues/3)
+
+- **Repo**: nsheaps/farish
+- **Blocked by**: nsheaps/agents#170
+- **What**: Pre-existing JSON task files left over before task-utils standardised on YAML need to be converted. Was tagged "skipped" in the R1–R6 report ([report `.claude/tmp/task-utils-redesign-report.md`](https://github.com/nsheaps/agents/blob/claude/ai-3d-model-generator-XjoUi/.claude/tmp/task-utils-redesign-report.md) §"Skipped Items"). Should use the same conversion logic as `task-sync-from-legacy.sh` (jq pipeline).
+- **Related**: nsheaps/farish PR #2 (legacy migration in progress).
+
+## Items intentionally NOT created as issues
+
+- **`jack#83` lint flake** (aqua/401 on `cli/cli`, `mikefarah/yq`, `claude-utils` during mise install when GH App token isn't ready before mise runs) — already tracked at [nsheaps/.ai-agent-jack#83](https://github.com/nsheaps/.ai-agent-jack/issues/83). Comment there rather than duplicate.
+- **Stale `~/.claude/tasks/<sid>/<id>.{json,yaml}` legacy in_progress files on the agents host** — handler decision in plan §"Decisions for handler" item 5: leave alone (won't be scanned post-redesign; become unreachable when native is off).
+- **PR #157 title/body update + monitor to merge** — operational; handled directly via `gh pr edit` + the existing PR-monitoring discipline, not a separate issue.
+
+## Dependency chain
+
+```
+#168 R7 validation  →  #169 auto-version-bump fix  →  #170 plugin-settings-lib promotion  →  farish#3 YAML migration
+```
+
+Linear chain at the handler's request ("execute in order"). True dependencies are weaker:
+
+- #168 genuinely blocks merge of PR #157.
+- #169 is independent of #168 in code, but #157 must merge before any follow-on PR has a clean CI baseline.
+- #170 requires #157 to be merged AND an ai-mktpl-dependency mechanism to exist on agents repo.
+- farish#3 is independent of #168/#169/#170 but lower priority than fixing CI.

.claude/plans/task-utils-redesign.md

@@ -0,0 +1,142 @@
+# task-utils redesign — built-in task decoupling
+
+> Handler correction 2026-05-23 / 24. Step-2 added a dual-scan in
+> `require-task-in-progress.sh` / `task-store-lib.sh` / `task-invariant.sh` so
+> both project-local YAML AND legacy per-session JSON satisfy the in_progress
+> gate. Handler now wants the opposite architecture: MCP tools decoupled from
+> built-in, hooks env-var-aware, with a PostToolUse sync fallback for when
+> built-in is left enabled.
+
+## Authoritative env var
+
+**`CLAUDE_CODE_ENABLE_TASKS`** — controls native Claude Code Task tools
+(`TaskCreate`, `TaskUpdate`, `TaskList`, `TaskGet`).
+
+| Value                  | Effect                                                                                                                           |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `0`/`false`/`off`/`no` | Native tasks DISABLED — only MCP path                                                                                            |
+| unset + TTY            | DEFAULT ON — native tasks active                                                                                                 |
+| unset + non-TTY        | DEFAULT OFF — Claude Code web, headless, piped contexts                                                                          |
+| `1`/`true`/`on`        | Forced ON (VSCode bug per [GH#23874](https://github.com/anthropics/claude-code/issues/23874) — `=1` may not re-enable in VSCode) |
+
+Source: [Tools Reference v2.1.142+](https://code.claude.com/docs/en/tools-reference.md).
+
+## Target architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ MCP server (task_create, task_update, ...)                   │
+│ • Reads/writes project-local YAML ONLY                       │
+│ • No awareness of ~/.claude/tasks/<session>/                 │
+│ • git-helper.ts auto-commits on every write (unchanged)       │
+└──────────────────────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────────────────────┐
+│ Hooks                                                         │
+│                                                               │
+│ PreToolUse:Write|Edit|MultiEdit|NotebookEdit                  │
+│   → task-sync-pull.sh (throttled pull, unchanged)             │
+│   → require-task-in-progress.sh                                │
+│      • Scans ONLY flat (project-local) YAML store              │
+│      • No legacy / JSON scan                                   │
+│                                                               │
+│ PreToolUse:TaskCreate|TaskUpdate                              │
+│   → task-invariant.sh (0-or-1 scan, flat YAML only)            │
+│   → task-native-warning.sh (NEW)                               │
+│      • Skip if CLAUDE_CODE_ENABLE_TASKS=0                      │
+│      • Else mode-based: silent | warn | block                  │
+│                                                               │
+│ PostToolUse:TaskCreate|TaskUpdate                             │
+│   → task-sync-from-legacy.sh (NEW, replaces task-auto-commit) │
+│      • Skip if CLAUDE_CODE_ENABLE_TASKS=0                      │
+│      • Copy ~/.claude/tasks/<sid>/<id>.{json,yaml}             │
+│        → <flat_store>/<id>.yaml                                │
+│      • git add + commit + push                                 │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## Phase plan
+
+### Phase R1 — Unwind dual-scan (sub-agent's RC3 fix reversal)
+
+Files in `plugins/claude-code/task-utils/`:
+
+- `hooks/task-store-lib.sh`: `count_in_progress_flat` back to YAML-only.
+- `hooks/task-invariant.sh`: 0-or-1 scan back to flat YAML only.
+- `hooks/require-task-in-progress.sh`: drop `LEGACY_STORE` resolution + count.
+- Update affected hook-integration tests.
+
+### Phase R2 — Env-var detection helper
+
+- New `hooks/builtin-tasks-detect.sh` (sourceable lib):
+  ```bash
+  # is_builtin_tasks_enabled — returns 0 (true) if native Task tools active
+  # Respects CLAUDE_CODE_ENABLE_TASKS env var with same semantics as
+  # Claude Code itself; falls back to TTY check when var is unset.
+  ```
+- Doc in plugin README: env var semantics + `TASK_UTILS_NATIVE_TASK_MODE`.
+
+### Phase R3 — PostToolUse sync hook
+
+- New `hooks/task-sync-from-legacy.sh`:
+  - Skip if built-in disabled (sourced helper).
+  - Resolve legacy file `~/.claude/tasks/<sid>/<id>.{json,yaml}` from tool result.
+  - Convert JSON → YAML if needed; copy to `<flat_store>/<id>.yaml`.
+  - `git add <file> && git commit -m 'chore(tasks): sync task <id> from native' && git push` (best-effort, exit 0 always).
+  - Log to `.claude/logs/task-sync-from-legacy.log`.
+- `hooks/hooks.json`: remove `task-auto-commit.sh` entry, register the new hook.
+- Delete `hooks/task-auto-commit.sh`.
+
+### Phase R4 — PreToolUse warning/block
+
+- New `hooks/task-native-warning.sh`:
+  - Skip if built-in disabled.
+  - Read `TASK_UTILS_NATIVE_TASK_MODE` (default `warn`).
+  - `silent` → exit 0.
+  - `warn` → `additionalContext` recommending `CLAUDE_CODE_ENABLE_TASKS=0` + use MCP `mcp__task-utils__task_create` etc. Allow.
+  - `block` → `permissionDecision: deny` with same recommendation.
+- `hooks/hooks.json`: register PreToolUse on `TaskCreate|TaskUpdate` after `task-invariant.sh`.
+
+### Phase R5 — MCP decoupling audit
+
+- Grep `mcp/src/` for `legacy`, `~/.claude/tasks`, `session_id`-keyed paths.
+- Remove any references to the legacy store from the MCP server (per the step-2 report, server already writes project-local — verify and clean up).
+
+### Phase R6 — Tests + version + docs
+
+- Update bun test suite to reflect:
+  - Single-store scan in hooks (YAML only).
+  - Env-var-aware skip in sync + warning hooks.
+  - 3-mode warning behavior.
+- Update SKILL.md (`task-utils:manage-tasks`), README.
+- Bump version `0.1.5` → `0.2.0` (behavior change; minor bump since users who relied on dual-scan need to adjust).
+
+### Phase R7 — Validate in this session
+
+- Add to `agents/.claude/settings.json` `"env"` block: `"CLAUDE_CODE_ENABLE_TASKS": "0"`.
+- Restart this session.
+- Verify native Task tools absent (no `TaskCreate` in available tools).
+- Verify MCP `mcp__task-utils__task_create` works + auto-commits.
+- Verify write-gate denies with no in_progress, allows after MCP task is in_progress.
+
+## Decisions for handler
+
+1. **Default `TASK_UTILS_NATIVE_TASK_MODE`?** Recommend `warn` — least surprising; surfaces the issue without breaking workflows that left native on.
+2. **Config mechanism — env var or plugin config file?** Recommend env var (`TASK_UTILS_NATIVE_TASK_MODE`). Simpler. Can promote to a config file later if it grows.
+3. **Version bump — patch (`0.1.6`) or minor (`0.2.0`)?** Recommend `0.2.0`. The gate's accepted-tasks set changes; that's user-visible.
+4. **Disable native tasks for agents repo?** Recommend yes — add `CLAUDE_CODE_ENABLE_TASKS=0` to `agents/.claude/settings.json` so the session this PR ships with uses MCP-only.
+5. **Stale legacy `~/.claude/tasks/<sid>/` in_progress tasks (4 found on disk)** — leave them alone (won't be scanned post-redesign), or sweep them as part of R7? Recommend: leave; they're per-session and become unreachable when native is off.
+
+## What does NOT change
+
+- MCP server's `git-helper.ts` auto-commit on MCP task writes (already correct).
+- `task-sync-pull.sh` throttled pre-write pull (unchanged).
+- `task-scope-guard.sh` UserPromptSubmit advisory (unchanged).
+- The YAML migration of farish tasks (committed `c8fb2ca` in nsheaps/farish).
+- `data-storage-using-the-filesystem` skill in the new `plugin-dev` plugin.
+
+## Out of scope (separate tickets)
+
+- The `auto-version-bump` CI workflow failure on `nsheaps/agents` — confirmed not transient; the workflow tries to bump a version that's already been bumped manually, hitting a git checkout conflict. Needs a workflow fix (detect already-bumped state and exit cleanly).
+- `jack#83` lint failure — pre-existing aqua/401 with mise + `gh`/`jq` tool pins. Out of scope here.
+- RC2 atomicity veto + RC4 scope-creep advisory — added in step-2e and left alone for now.

.gitignore

@@ -6,6 +6,9 @@ yarn.lock
 dist/
 # Exception: agent-utils plugin ships pre-built bun bundles for hook invocation
 !plugins/claude-code/agent-utils/dist/
+# Note: task-utils ships the MCP server as SOURCE only — its native binary is
+# built on-device on first use (see plugins/claude-code/task-utils/mcp/build.sh),
+# so task-utils/mcp/dist/ stays ignored.
 *.tar.gz
 
 # IDE
@@ -36,5 +39,8 @@ test/tmp/
 # Team scratch/temp files
 .claude/tmp/
 
+# Sub-agent git worktrees (local working areas, never committed)
+.claude/worktrees/
+
 # Logs
 *.log

mise.toml

@@ -2,9 +2,16 @@
 # postgres = "https://github.com/mise-plugins/vfox-postgres.git"
 
 [tools]
-jq = "latest"
-bun = "1.3.13"
-"npm:@anthropic-ai/claude-code" = "latest"
+jq = "1.8.1"
+bun = "1.3.14"
+node = "24.15.0"
+# `depends` ensures node is fully installed before npm:@anthropic-ai/claude-code
+# tries to use it. depends does NOT control PATH ordering — see
+# https://mise.jdx.dev/dev-tools/#tool-dependencies. PATH conflicts between
+# tools that expose the same binary name (e.g., node and claude-code both
+# expose `claude`) are resolved at runtime by `mise which claude` lookups
+# rather than relying on activation order; bin/agent uses that explicitly.
+"npm:@anthropic-ai/claude-code" = { version = "2.1.128", depends = "node" }
 "pipx:litellm" = { version = "1.83.14", extras = "proxy" }
 tilt = "0.37.3"
 
@@ -61,9 +68,27 @@ done
 echo "All lint checks passed."
 """
 
+[tasks.build-task-mcp]
+description = "Compile the task-utils MCP server native binary (mcp/dist/task-mcp) — local-dev/CI check; end users build on-device via mcp/build.sh"
+dir = "plugins/claude-code/task-utils/mcp"
+run = """
+bun install
+bun build --compile --outfile dist/task-mcp src/server.ts
+echo "Built plugins/claude-code/task-utils/mcp/dist/task-mcp"
+"""
+
+[tasks.test-task-mcp]
+description = "Run the task-utils MCP server unit + integration tests + hook write-gate test"
+depends = ["build-task-mcp"]
+run = """
+cd plugins/claude-code/task-utils/mcp && bun test
+cd "$MISE_PROJECT_ROOT" && bash plugins/claude-code/task-utils/mcp/test/hook-integration.test.sh
+"""
+
 [tasks.test]
 description = "Run tests"
-run = "bun test"
+depends = ["test-task-mcp"]
+run = "echo 'All tests passed'"
 
 [tasks.check]
 description = "Run all checks (format + lint + test)"

mise/tasks/validate

@@ -2,6 +2,17 @@
 #MISE description="Validate plugin structure and marketplace consistency"
 set -e
 
+# claude-code's native binary is downloaded by a postinstall script that mise's
+# npm backend skips (it installs with --ignore-scripts), so a fresh install
+# leaves `claude` non-functional ("claude native binary not installed"). Run
+# the postinstall explicitly before validate-plugin invokes `claude`.
+cc_dir="$(mise where npm:@anthropic-ai/claude-code 2>/dev/null || true)"
+cc_install="${cc_dir}/lib/node_modules/@anthropic-ai/claude-code/install.cjs"
+if [ -n "$cc_dir" ] && [ -f "$cc_install" ]; then
+  echo "Ensuring claude-code native binary is installed..."
+  node "$cc_install"
+fi
+
 mise run validate-marketplace
 
 VALID=true

plugins/claude-code/agent-utils/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-utils",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Agent infrastructure: skills for multi-agent orchestration + tools for settings drift detection and 2-stage settings merge + rules-sync (SessionStart symlink of plugin rules into the project) + upstream-check (throttled UserPromptSubmit hook that surfaces upstream agent-repo changes and dirty-state nags).",
   "author": {
     "name": "Nathan Heaps",

plugins/claude-code/agent-utils/skills/tmux-usage/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: tmux-usage
+description: Use when working with tmux in Claude Code agent team sessions. Covers core tmux concepts, pane/window management, session attachment, and agent-team-specific tmux patterns. Trigger phrases — "tmux", "terminal multiplexer", "attach to session", "split panes", "switch windows", "tmux shortcuts".
+---
+
 # tmux Usage for Agent Teams
 
 How to use tmux effectively when working with Claude Code agent teams.

plugins/claude-code/agent-utils/skills/writing-agent-team-agents/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: writing-agent-team-agents
+description: Use when creating or updating agent files for the agent-team project. Covers agent file structure, frontmatter schema, persona files, and how to write system prompts. Trigger phrases — "create an agent", "add a new teammate", "write an agent file", "what goes in an agent file", "agent file structure".
+---
+
 # Writing Agent Team Agents
 
 How to create and maintain agent files for the agent-team project.