opencode-hive 1.1.0 → 1.3.0

package/dist/index.js

@@ -1,18 +1,22 @@
 import { createRequire } from "node:module";
 var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/index.ts
-import * as path7 from "path";
+import * as path8 from "path";
 import * as os from "os";
 
 // ../../node_modules/zod/v4/classic/external.js
@@ -12336,8 +12340,260 @@ function tool(input) {
 }
 tool.schema = exports_external;
 // src/skills/registry.generated.ts
-var BUILTIN_SKILL_NAMES = ["brainstorming", "code-reviewer", "dispatching-parallel-agents", "executing-plans", "onboarding", "parallel-exploration", "systematic-debugging", "test-driven-development", "verification-before-completion", "writing-plans"];
+var BUILTIN_SKILL_NAMES = ["agents-md-mastery", "brainstorming", "code-reviewer", "dispatching-parallel-agents", "docker-mastery", "executing-plans", "parallel-exploration", "systematic-debugging", "test-driven-development", "verification-before-completion", "writing-plans"];
 var BUILTIN_SKILLS = [
+  {
+    name: "agents-md-mastery",
+    description: "Use when bootstrapping, updating, or reviewing AGENTS.md — teaches what makes effective agent memory, how to structure sections, signal vs noise filtering, and when to prune stale entries",
+    template: `# AGENTS.md Mastery
+
+## Overview
+
+**AGENTS.md is pseudo-memory loaded at session start.** Every line shapes agent behavior for the entire session. Quality beats quantity. Write for agents, not humans.
+
+Unlike code comments or READMEs, AGENTS.md entries persist across all agent sessions. A bad entry misleads agents hundreds of times. A missing entry causes the same mistake repeatedly.
+
+**Core principle:** Optimize for agent comprehension and behavioral change, not human readability.
+
+## The Iron Law
+
+\`\`\`
+EVERY ENTRY MUST CHANGE AGENT BEHAVIOR
+\`\`\`
+
+If an entry doesn't:
+- Prevent a specific mistake
+- Enable a capability the agent would otherwise miss
+- Override a default assumption that breaks in this codebase
+
+...then it doesn't belong in AGENTS.md.
+
+**Test:** Would a fresh agent session make a mistake without this entry? If no → noise.
+
+## When to Use
+
+| Trigger | Action |
+|---------|--------|
+| New project bootstrap | Write initial AGENTS.md with build/test/style basics |
+| Feature completion | Sync new learnings via \`hive_agents_md\` tool |
+| Periodic review | Audit for stale/redundant entries (quarterly) |
+| Quality issues | Agent repeating mistakes? Check if AGENTS.md has the fix |
+
+## What Makes Good Agent Memory
+
+### Signal Entries (Keep)
+
+✅ **Project-specific conventions:**
+- "We use Zustand, not Redux — never add Redux"
+- "Auth lives in \`/lib/auth\` — never create auth elsewhere"
+- "Run \`bun test\` not \`npm test\` (we don't use npm)"
+
+✅ **Non-obvious patterns:**
+- "Use \`.js\` extension for local imports (ESM requirement)"
+- "Worktrees don't share \`node_modules\` — run \`bun install\` in each"
+- "SandboxConfig is in \`dockerSandboxService.ts\`, NOT \`types.ts\`"
+
+✅ **Gotchas that break builds:**
+- "Never use \`ensureDirSync\` — doesn't exist. Use \`ensureDir\` (sync despite name)"
+- "Import from \`../utils/paths.js\` not \`./paths\` (ESM strict)"
+
+### Noise Entries (Remove)
+
+❌ **Agent already knows:**
+- "This project uses TypeScript" (agent detects from files)
+- "We follow semantic versioning" (universal convention)
+- "Use descriptive variable names" (generic advice)
+
+❌ **Irrelevant metadata:**
+- "Created on January 2024"
+- "Originally written by X"
+- "License: MIT" (in LICENSE file already)
+
+❌ **Describes what code does:**
+- "FeatureService manages features" (agent can read code)
+- "The system uses git worktrees" (observable from commands)
+
+### Rule of Thumb
+
+**Signal:** Changes how agent acts  
+**Noise:** Documents what agent observes
+
+## Section Structure for Fast Comprehension
+
+Agents read AGENTS.md top-to-bottom once at session start. Put high-value info first:
+
+\`\`\`markdown
+# Project Name
+
+## Build & Test Commands
+# ← Agents need this IMMEDIATELY
+bun run build
+bun run test
+bun run release:check
+
+## Code Style
+# ← Prevents syntax/import errors
+- Semicolons: Yes
+- Quotes: Single
+- Imports: Use \`.js\` extension
+
+## Architecture
+# ← Key directories, where things live
+packages/
+├── hive-core/      # Shared logic
+├── opencode-hive/  # Plugin
+└── vscode-hive/    # Extension
+
+## Important Patterns
+# ← How to do common tasks correctly
+Use \`readText\` from paths.ts, not fs.readFileSync
+
+## Gotchas & Anti-Patterns
+# ← Things that break or mislead
+NEVER use \`ensureDirSync\` — doesn't exist
+\`\`\`
+
+**Keep total under 500 lines.** Beyond that, agents lose focus and miss critical entries.
+
+## The Sync Workflow
+
+After completing a feature, sync learnings to AGENTS.md:
+
+1. **Trigger sync:**
+   \`\`\`typescript
+   hive_agents_md({ action: 'sync', feature: 'feature-name' })
+   \`\`\`
+
+2. **Review each proposal:**
+   - Read the proposed change
+   - Ask: "Does this change agent behavior?"
+   - Check: Is this already obvious from code/files?
+
+3. **Accept signal, reject noise:**
+   - ❌ "TypeScript is used" → Agent detects this
+   - ✅ "Use \`.js\` extension for imports" → Prevents build failures
+
+4. **Apply approved changes:**
+   \`\`\`typescript
+   hive_agents_md({ action: 'apply' })
+   \`\`\`
+
+**Warning:** Don't auto-approve all proposals. One bad entry pollutes all future sessions.
+
+## When to Prune
+
+Remove entries when they become:
+
+**Outdated:**
+- "We use Redux" → Project migrated to Zustand
+- "Node 16 compatibility required" → Now on Node 22
+
+**Redundant:**
+- "Use single quotes" + "Strings use single quotes" → Keep one
+- Near-duplicates in different sections
+
+**Too generic:**
+- "Write clear code" → Applies to any project
+- "Test your changes" → Universal advice
+
+**Describing code:**
+- "TaskService manages tasks" → Agent can read \`TaskService\` class
+- "Worktrees are in \`.hive/.worktrees/\`" → Observable from filesystem
+
+**Proven unnecessary:**
+- Entry added 6 months ago, but agents haven't hit that issue since
+
+## Red Flags
+
+| Warning Sign | Why It's Bad | Fix |
+|-------------|-------------|-----|
+| AGENTS.md > 800 lines | Agents lose focus, miss critical info | Prune aggressively |
+| Describes what code does | Agent can read code | Remove descriptions |
+| Missing build/test commands | First thing agents need | Add at top |
+| No gotchas section | Agents repeat past mistakes | Document failure modes |
+| Generic best practices | Doesn't change behavior | Remove or make specific |
+| Outdated patterns | Misleads agents | Prune during sync |
+
+## Anti-Patterns
+
+| Anti-Pattern | Better Approach |
+|-------------|----------------|
+| "Document everything" | Document only what changes behavior |
+| "Keep for historical record" | Version control is history |
+| "Might be useful someday" | Add when proven necessary |
+| "Explains the system" | Agents read code for that |
+| "Comprehensive reference" | AGENTS.md is a filter, not docs |
+
+## Good Examples
+
+**Build Commands (High value, agents need immediately):**
+\`\`\`markdown
+## Build & Test Commands
+bun run build              # Build all packages
+bun run test               # Run all tests
+bun run release:check      # Full CI check
+\`\`\`
+
+**Project-Specific Convention (Prevents mistakes):**
+\`\`\`markdown
+## Code Style
+- Imports: Use \`.js\` extension for local imports (ESM requirement)
+- Paths: Import from \`../utils/paths.js\` never \`./paths\`
+\`\`\`
+
+**Non-Obvious Gotcha (Prevents build failure):**
+\`\`\`markdown
+## Important Patterns
+Use \`ensureDir\` from paths.ts — sync despite name
+NEVER use \`ensureDirSync\` (doesn't exist)
+\`\`\`
+
+## Bad Examples
+
+**Generic advice (agent already knows):**
+\`\`\`markdown
+## Best Practices
+- Use meaningful variable names
+- Write unit tests
+- Follow DRY principle
+\`\`\`
+
+**Describes code (agent can read it):**
+\`\`\`markdown
+## Architecture
+The FeatureService class manages features. It has methods
+for create, read, update, and delete operations.
+\`\`\`
+
+**Irrelevant metadata:**
+\`\`\`markdown
+## Project History
+Created in January 2024 by the platform team.
+Originally built for internal use.
+\`\`\`
+
+## Verification
+
+Before finalizing AGENTS.md updates:
+
+- [ ] Every entry answers: "What mistake does this prevent?"
+- [ ] No generic advice that applies to all projects
+- [ ] Build/test commands are first
+- [ ] Gotchas section exists and is populated
+- [ ] Total length under 500 lines (800 absolute max)
+- [ ] No entries describing what code does
+- [ ] Fresh agent session would benefit from each entry
+
+## Summary
+
+AGENTS.md is **behavioral memory**, not documentation:
+- Write for agents, optimize for behavior change
+- Signal = prevents mistakes, Noise = describes observables
+- Sync after features, prune quarterly
+- Test: Would agent make a mistake without this entry?
+
+**Quality > quantity. Every line counts.**`
+  },
   {
     name: "brainstorming",
     description: "Use before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.",
@@ -12795,6 +13051,351 @@ From debugging session (2025-10-03):
 - All investigations completed concurrently
 - All fixes integrated successfully
 - Zero conflicts between agent changes`
+  },
+  {
+    name: "docker-mastery",
+    description: "Use when working with Docker containers — debugging container failures, writing Dockerfiles, docker-compose for integration tests, image optimization, or deploying containerized applications",
+    template: `# Docker Mastery
+
+## Overview
+
+Docker is a **platform for building, shipping, and running applications**, not just isolation.
+
+Agents should think in containers: reproducible environments, declarative dependencies, isolated execution.
+
+**Core principle:** Containers are not virtual machines. They share the kernel but isolate processes, filesystems, and networks.
+
+**Violating the letter of these guidelines is violating the spirit of containerization.**
+
+## The Iron Law
+
+\`\`\`
+UNDERSTAND THE CONTAINER BEFORE DEBUGGING INSIDE IT
+\`\`\`
+
+Before exec'ing into a container or adding debug commands:
+1. Check the image (what's installed?)
+2. Check mounts (what host files are visible?)
+3. Check environment variables (what config is passed?)
+4. Check the Dockerfile (how was it built?)
+
+Random debugging inside containers wastes time. Context first, then debug.
+
+## When to Use
+
+Use this skill when working with:
+- **Container build failures** - Dockerfile errors, missing dependencies
+- **Test environment setup** - Reproducible test environments across machines
+- **Integration test orchestration** - Multi-service setups (DB + API + tests)
+- **Dockerfile authoring** - Writing efficient, maintainable Dockerfiles
+- **Image size optimization** - Reducing image size, layer caching
+- **Deployment** - Containerized application deployment
+- **Sandbox debugging** - Issues with Hive's Docker sandbox mode
+
+**Use this ESPECIALLY when:**
+- Tests pass locally but fail in CI (environment mismatch)
+- "Works on my machine" problems
+- Need to test against specific dependency versions
+- Multiple services must coordinate (database + API)
+- Building for production deployment
+
+## Core Concepts
+
+### Images vs Containers
+
+- **Image**: Read-only template (built from Dockerfile)
+- **Container**: Running instance of an image (ephemeral by default)
+
+\`\`\`bash
+# Build once
+docker build -t myapp:latest .
+
+# Run many times
+docker run --rm myapp:latest
+docker run --rm -e DEBUG=true myapp:latest
+\`\`\`
+
+**Key insight:** Changes inside containers are lost unless committed or volumes are used.
+
+### Volumes & Mounts
+
+Mount host directories into containers for persistence and code sharing:
+
+\`\`\`bash
+# Mount current directory to /app in container
+docker run -v $(pwd):/app myapp:latest
+
+# Hive worktrees are mounted automatically
+# Your code edits (via Read/Write/Edit tools) affect the host
+# Container sees the same files at runtime
+\`\`\`
+
+**How Hive uses this:** Worktree is mounted into container, so file tools work on host, bash commands run in container.
+
+### Multi-Stage Builds
+
+Minimize image size by using multiple FROM statements:
+
+\`\`\`dockerfile
+# Build stage (large, has compilers)
+FROM node:22 AS builder
+WORKDIR /app
+COPY package.json bun.lockb ./
+RUN bun install
+COPY . .
+RUN bun run build
+
+# Runtime stage (small, production only)
+FROM node:22-slim
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+CMD ["node", "dist/index.js"]
+\`\`\`
+
+**Result:** Builder tools (TypeScript, bundlers) not included in final image.
+
+### Docker Compose for Multi-Service Setups
+
+Define multiple services in \`docker-compose.yml\`:
+
+\`\`\`yaml
+version: '3.8'
+services:
+  db:
+    image: postgres:15
+    environment:
+      POSTGRES_PASSWORD: testpass
+    ports:
+      - "5432:5432"
+  
+  api:
+    build: .
+    environment:
+      DATABASE_URL: postgres://db:5432/testdb
+    depends_on:
+      - db
+    ports:
+      - "3000:3000"
+\`\`\`
+
+Run with: \`docker-compose up -d\`
+Teardown with: \`docker-compose down\`
+
+### Network Modes
+
+- **bridge** (default): Isolated network, containers can talk to each other by name
+- **host**: Container uses host's network directly (no isolation)
+- **none**: No network access
+
+**When to use host mode:** Debugging network issues, accessing host services directly.
+
+## Common Patterns
+
+### Debug a Failing Container
+
+**Problem:** Container exits immediately, logs unclear.
+
+**Pattern:**
+1. Run interactively with shell:
+   \`\`\`bash
+   docker run -it --entrypoint sh myapp:latest
+   \`\`\`
+2. Inspect filesystem, check if dependencies exist:
+   \`\`\`bash
+   ls /app
+   which node
+   cat /etc/os-release
+   \`\`\`
+3. Run command manually to see full error:
+   \`\`\`bash
+   node dist/index.js
+   \`\`\`
+
+### Integration Tests with Docker Compose
+
+**Pattern:**
+1. Define services in \`docker-compose.test.yml\`
+2. Add wait logic (wait for DB to be ready)
+3. Run tests
+4. Teardown
+
+\`\`\`yaml
+# docker-compose.test.yml
+services:
+  db:
+    image: postgres:15
+    environment:
+      POSTGRES_PASSWORD: test
+  test:
+    build: .
+    command: bun run test:integration
+    depends_on:
+      - db
+    environment:
+      DATABASE_URL: postgres://postgres:test@db:5432/testdb
+\`\`\`
+
+\`\`\`bash
+docker-compose -f docker-compose.test.yml up --abort-on-container-exit
+docker-compose -f docker-compose.test.yml down
+\`\`\`
+
+### Optimize Dockerfile
+
+**Anti-pattern:**
+\`\`\`dockerfile
+FROM node:22
+WORKDIR /app
+COPY . .              # Copies everything (including node_modules, .git)
+RUN bun install       # Invalidates cache on any file change
+CMD ["bun", "run", "start"]
+\`\`\`
+
+**Optimized:**
+\`\`\`dockerfile
+FROM node:22-slim     # Use slim variant
+WORKDIR /app
+
+# Copy dependency files first (cache layer)
+COPY package.json bun.lockb ./
+RUN bun install --production
+
+# Copy source code (changes frequently)
+COPY src ./src
+COPY tsconfig.json ./
+
+CMD ["bun", "run", "start"]
+\`\`\`
+
+**Add \`.dockerignore\`:**
+\`\`\`
+node_modules
+.git
+.env
+*.log
+dist
+.DS_Store
+\`\`\`
+
+### Handle Missing Dependencies
+
+**Problem:** Command fails with "not found" in container.
+
+**Pattern:**
+1. Check if dependency is in image:
+   \`\`\`bash
+   docker run -it myapp:latest which git
+   \`\`\`
+2. If missing, add to Dockerfile:
+   \`\`\`dockerfile
+   RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
+   \`\`\`
+3. Or use a richer base image (e.g., \`node:22\` instead of \`node:22-slim\`).
+
+## Hive Sandbox Integration
+
+### How Hive Wraps Commands
+
+When sandbox mode is active (\`sandbox: 'docker'\` in config):
+1. Hive hook intercepts bash commands before execution
+2. Wraps with \`docker run --rm -v <worktree>:/workspace -w /workspace <image> sh -c "<command>"\`
+3. Command runs in container, but file edits (Read/Write/Edit) still affect host
+
+**Workers are unaware** — they issue normal bash commands, Hive handles containerization.
+
+### When Host Access is Needed
+
+Some operations MUST run on host:
+- **Git operations** (commit, push, branch) — repo state is on host
+- **Host-level tools** (Docker itself, system config)
+- **Cross-worktree operations** (accessing main repo from worktree)
+
+**Pattern:** Use \`HOST:\` prefix to escape sandbox:
+\`\`\`bash
+HOST: git status
+HOST: docker ps
+\`\`\`
+
+**If you need host access frequently:** Report as blocked and ask user if sandbox should be disabled for this task.
+
+### Persistent vs Ephemeral Containers
+
+**Current (v1.2.0):** Each command runs \`docker run --rm\` (ephemeral). State does NOT persist.
+
+Example: \`npm install lodash\` in one command → not available in next command.
+
+**Workaround:** Install dependencies in Dockerfile, not at runtime.
+
+**Future:** \`docker exec\` will reuse containers, persisting state across commands.
+
+### Auto-Detected Images
+
+Hive detects runtime from project files:
+- \`package.json\` → \`node:22-slim\`
+- \`requirements.txt\` / \`pyproject.toml\` → \`python:3.12-slim\`
+- \`go.mod\` → \`golang:1.22-slim\`
+- \`Cargo.toml\` → \`rust:1.77-slim\`
+- \`Dockerfile\` → Builds from project Dockerfile
+- Fallback → \`ubuntu:24.04\`
+
+**Override:** Set \`dockerImage\` in config (\`~/.config/opencode/agent_hive.json\`).
+
+## Red Flags - STOP
+
+If you catch yourself:
+- Installing packages on host instead of in Dockerfile
+- Running \`docker build\` without \`.dockerignore\` (cache invalidation)
+- Using \`latest\` tag in production (non-reproducible)
+- Ignoring container exit codes (hides failures)
+- Assuming state persists between \`docker run --rm\` commands
+- Using absolute host paths in Dockerfile (not portable)
+- Copying secrets into image layers (leaks credentials)
+
+**ALL of these mean: STOP. Review pattern.**
+
+## Anti-Patterns
+
+| Excuse | Reality |
+|--------|---------|
+| "I'll just run it on host" | Container mismatch bugs are worse to debug later. Build happens in container anyway. |
+| "Works in my container, don't need CI" | CI uses different cache state. Always test in CI-like environment. |
+| "I'll optimize the Dockerfile later" | Later never comes. Large images slow down deployments now. |
+| "latest tag is fine for dev" | Dev should match prod. Pin versions or face surprises. |
+| "Don't need .dockerignore, COPY is fast" | Invalidates cache on every file change. Wastes minutes per build. |
+| "Install at runtime, not in image" | Ephemeral containers lose state. Slows down every command. |
+| "Skip depends_on, services start fast" | Race conditions in integration tests. Use wait-for-it or health checks. |
+
+## Verification Before Completion
+
+Before marking Docker work complete:
+
+- [ ] Container runs successfully: \`docker run --rm <image> <command>\` exits 0
+- [ ] Tests pass inside container (not just on host)
+- [ ] No host pollution (dependencies installed in container, not host)
+- [ ] \`.dockerignore\` exists if using \`COPY . .\`
+- [ ] Image tags are pinned (not \`latest\`) for production
+- [ ] Multi-stage build used if applicable (separate build/runtime)
+- [ ] Integration tests teardown properly (\`docker-compose down\`)
+
+**If any fail:** Don't claim success. Fix or report blocker.
+
+## Quick Reference
+
+| Task | Command Pattern |
+|------|----------------|
+| **Debug container** | \`docker run -it --entrypoint sh <image>\` |
+| **Run with mounts** | \`docker run -v $(pwd):/app <image>\` |
+| **Multi-service tests** | \`docker-compose up --abort-on-container-exit\` |
+| **Check image contents** | \`docker run --rm <image> ls /app\` |
+| **Optimize build** | Add \`.dockerignore\`, use multi-stage, pin versions |
+| **Escape Hive sandbox** | Prefix with \`HOST:\` (e.g., \`HOST: git status\`) |
+
+## Related Skills
+
+- **hive_skill:systematic-debugging** - When container behavior is unexpected
+- **hive_skill:test-driven-development** - Write tests that run in containers
+- **hive_skill:verification-before-completion** - Verify tests pass in container before claiming done`
   },
   {
     name: "executing-plans",
@@ -12857,8 +13458,8 @@ Based on feedback:
 ### Step 6: Complete Development
 
 After all tasks complete and verified:
-- Announce: "I'm using the finishing-a-development-branch skill to complete this work."
-- **REQUIRED SUB-SKILL:** Use hive_skill:finishing-a-development-branch
+- Announce: "I'm using the verification-before-completion skill to complete this work."
+- **REQUIRED SUB-SKILL:** Use hive_skill:verification-before-completion
 - Follow that skill to verify tests, present options, execute choice
 
 ## When to Stop and Ask for Help
@@ -12886,66 +13487,6 @@ After all tasks complete and verified:
 - Reference skills when plan says to
 - Between batches: just report and wait
 - Stop when blocked, don't guess`
-  },
-  {
-    name: "onboarding",
-    description: "Ask about workflow preferences and store them in .hive/contexts/preferences.md before proceeding.",
-    template: `# Onboarding Preferences
-
-## Overview
-
-Gather workflow preferences so the assistant can match the user's desired working style.
-
-## When to Ask
-
-- **Immediately when the skill is loaded**, before any other work.
-- If \`.hive/contexts/preferences.md\` does not exist, start onboarding.
-- If later a decision is ambiguous and preferences are missing, ask again.
-
-## Preference Storage
-
-Use \`hive_context_write\` to write \`.hive/contexts/preferences.md\` with this exact template:
-
-\`\`\`
-# Preferences
-
-## Exploration Style
-sync
-
-## Research Depth
-medium
-
-## Confirmation Level
-standard
-
-## Commit Behavior
-ask-before-commit
-\`\`\`
-
-## If Preferences Already Exist
-
-Follow the same pattern used in \`packages/vscode-hive/src/tools/plan.ts\`:
-
-1. Use \`contextService.list(feature)\` to detect existing contexts.
-2. Ask **"Preferences already exist. Keep or overwrite?"** using the \`question()\` tool.
-3. If keep → continue using existing preferences.
-4. If overwrite → collect new answers and write them with \`hive_context_write\`.
-
-## Questions to Ask (Always use \`question()\`)
-
-Ask one at a time, with the provided options. Store the answers in \`.hive/contexts/preferences.md\`.
-
-1. **Exploration Style:** sync | async
-2. **Research Depth:** shallow | medium | deep
-3. **Confirmation Level:** minimal | standard | high
-4. **Commit Behavior:** ask-before-commit | auto-commit | never-commit
-
-## Requirements
-
-- Use the \`question()\` tool (no plain text questions).
-- Ask immediately when the skill loads if preferences are missing.
-- If later a decision is ambiguous and preferences are missing, ask again.
-- Always store answers using \`hive_context_write\` with the template above.`
   },
   {
     name: "parallel-exploration",
@@ -13837,7 +14378,7 @@ Never fix bugs without a test.
 
 ## Testing Anti-Patterns
 
-When adding mocks or test utilities, read @testing-anti-patterns.md to avoid common pitfalls:
+When adding mocks or test utilities, avoid common pitfalls:
 - Testing mock behavior instead of real behavior
 - Adding test-only methods to production classes
 - Mocking without understanding dependencies
@@ -14100,6 +14641,12 @@ Always include **Depends on** for each task. Use \`none\` to enable parallel sta
 **Verify**:
 - [ ] Run: \`{command}\` → {expected}
 - [ ] {Additional acceptance criteria}
+
+All verification MUST be agent-executable (no human intervention):
+✅ \`bun test\` → all pass
+✅ \`curl -X POST /api/x\` → 201
+❌ "User manually tests..."
+❌ "Visually confirm..."
 \`\`\`\`
 
 ## Remember
@@ -14108,6 +14655,7 @@ Always include **Depends on** for each task. Use \`none\` to enable parallel sta
 - Exact commands with expected output
 - Reference relevant skills with @ syntax
 - DRY, YAGNI, TDD, frequent commits
+- All acceptance criteria must be agent-executable (zero human intervention)
 
 ## Execution Handoff
 
@@ -14279,7 +14827,6 @@ Run \`hive_status()\` to detect phase:
 ## Universal (Always Active)
 
 ### Intent Classification
-
 | Intent | Signals | Action |
 |--------|---------|--------|
 | Trivial | Single file, <10 lines | Do directly |
@@ -14287,22 +14834,34 @@ Run \`hive_status()\` to detect phase:
 | Complex | 3+ files, multi-step | Full discovery → plan/delegate |
 | Research | Internal codebase exploration OR external data | Delegate to Scout (Explorer/Researcher/Retrieval) |
 
-### Canonical Delegation Threshold
+Intent Verbalization — verbalize before acting:
+> "I detect [type] intent — [reason]. Approach: [route]."
 
+| Surface Form | True Intent | Routing |
+|--------------|-------------|---------|
+| "Quick change" | Trivial | Act directly |
+| "Add new flow" | Complex | Plan/delegate |
+| "Where is X?" | Research | Scout exploration |
+| "Should we…?" | Ambiguous | Ask a question |
+
+### Canonical Delegation Threshold
 - Delegate to Scout when you cannot name the file path upfront, expect to inspect 2+ files, or the question is open-ended ("how/where does X work?").
 - Prefer \`task({ subagent_type: "scout-researcher", prompt: "..." })\` for single investigations.
 - Local \`read/grep/glob\` is acceptable only for a single known file and a bounded question.
 
 ### Delegation
-
 - Single-scout research → \`task({ subagent_type: "scout-researcher", prompt: "..." })\`
 - Parallel exploration → Load \`hive_skill("parallel-exploration")\` and follow the task mode delegation guidance.
 - Implementation → \`hive_worktree_create({ task: "01-task-name" })\` (creates worktree + Forager)
 
 During Planning, use \`task({ subagent_type: "scout-researcher", ... })\` for exploration (BLOCKING — returns when done). For parallel exploration, issue multiple \`task()\` calls in the same message.
 
-### Context Persistence
+**When NOT to delegate:**
+- Single-file, <10-line changes — do directly
+- Sequential operations where you need the result of step N for step N+1
+- Questions answerable with one grep + one file read
 
+### Context Persistence
 Save discoveries with \`hive_context_write\`:
 - Requirements and decisions
 - User preferences
@@ -14311,60 +14870,64 @@ Save discoveries with \`hive_context_write\`:
 When Scout returns substantial findings (3+ files discovered, architecture patterns, or key decisions), persist them to a feature context file via \`hive_context_write\`.
 
 ### Checkpoints
-
 Before major transitions, verify:
 - [ ] Objective clear?
 - [ ] Scope defined?
 - [ ] No critical ambiguities?
 
-### Loading Skills (On-Demand)
-
-Load when detailed guidance needed:
-- \`hive_skill("brainstorming")\` - exploring ideas and requirements
-- \`hive_skill("writing-plans")\` - structuring implementation plans
-- \`hive_skill("dispatching-parallel-agents")\` - parallel task delegation
-- \`hive_skill("parallel-exploration")\` - parallel read-only research via task() (Scout fan-out)
-- \`hive_skill("executing-plans")\` - step-by-step plan execution
+### Turn Termination
+Valid endings:
+- Ask a concrete question
+- Update draft + ask a concrete question
+- Explicitly state you are waiting on background work (tool/task)
+- Auto-transition to the next required action
 
-Load ONE skill at a time. Only when you need guidance beyond this prompt.
+NEVER end with:
+- "Let me know if you have questions"
+- Summary without a follow-up action
+- "When you're ready..."
 
+### Loading Skills (On-Demand)
+Load when detailed guidance needed:
+| Skill | Use when |
+|-------|----------|
+| \`hive_skill("brainstorming")\` | Exploring ideas and requirements |
+| \`hive_skill("writing-plans")\` | Structuring implementation plans |
+| \`hive_skill("dispatching-parallel-agents")\` | Parallel task delegation |
+| \`hive_skill("parallel-exploration")\` | Parallel read-only research via task() |
+| \`hive_skill("executing-plans")\` | Step-by-step plan execution |
+| \`hive_skill("systematic-debugging")\` | Bugs, test failures, unexpected behavior |
+| \`hive_skill("test-driven-development")\` | TDD approach |
+| \`hive_skill("verification-before-completion")\` | Before claiming work is complete or creating PRs |
+| \`hive_skill("docker-mastery")\` | Docker containers, debugging, compose |
+| \`hive_skill("agents-md-mastery")\` | AGENTS.md updates, quality review |
+
+Load one skill at a time, only when guidance is needed.
 ---
 
 ## Planning Phase
-
 *Active when: no approved plan exists*
 
 ### When to Load Skills
-
 - Exploring vague requirements → \`hive_skill("brainstorming")\`
 - Writing detailed plan → \`hive_skill("writing-plans")\`
 
-### AI-Slop Flags
-
-| Pattern | Ask |
-|---------|-----|
+### Planning Checks
+| Signal | Prompt |
+|--------|--------|
 | Scope inflation | "Should I include X?" |
 | Premature abstraction | "Abstract or inline?" |
 | Over-validation | "Minimal or comprehensive checks?" |
-
-### Challenge User Assumptions
-
-When a proposal relies on fragile assumptions, challenge them explicitly:
-
-- Identify the assumption and state it plainly.
-- Ask what changes if the assumption is wrong.
-- Offer a lean fallback that still meets core goals.
+| Fragile assumption | "If this assumption is wrong, what changes?" |
 
 ### Gap Classification
-
 | Gap | Action |
 |-----|--------|
-| Critical | ASK immediately |
+| Critical | Ask immediately |
 | Minor | Fix silently, note in summary |
 | Ambiguous | Apply default, disclose |
 
 ### Plan Output
-
 \`\`\`
 hive_feature_create({ name: "feature-name" })
 hive_plan_write({ content: "..." })
@@ -14375,12 +14938,11 @@ Plan includes: Discovery (Original Request, Interview Summary, Research Findings
 - References must use file:line format
 - Verify must include exact command + expected output
 
-Each task MUST declare dependencies with **Depends on**:
+Each task declares dependencies with **Depends on**:
 - **Depends on**: none for no dependencies / parallel starts
 - **Depends on**: 1, 3 for explicit task-number dependencies
 
 ### After Plan Written
-
 Ask user via \`question()\`: "Plan complete. Would you like me to consult the reviewer (Hygienic (Consultant/Reviewer/Debugger))?"
 
 If yes → \`task({ subagent_type: "hygienic", prompt: "Review plan..." })\`
@@ -14388,86 +14950,108 @@ If yes → \`task({ subagent_type: "hygienic", prompt: "Review plan..." })\`
 After review decision, offer execution choice (subagent-driven vs parallel session) consistent with writing-plans.
 
 ### Planning Iron Laws
-
-- Research BEFORE asking (use \`hive_skill("parallel-exploration")\` for multi-domain research)
+- Research before asking (use \`hive_skill("parallel-exploration")\` for multi-domain research)
 - Save draft as working memory
-- Don't implement (no edits/worktrees). Read-only exploration is allowed (local tools + Scout via task()).
+- Keep planning read-only (local tools + Scout via task())
+Read-only exploration is allowed.
+Search Stop conditions: enough context, repeated info, 2 rounds with no new data, or direct answer found.
 
 ---
 
 ## Orchestration Phase
-
 *Active when: plan approved, tasks exist*
 
 ### Task Dependencies (Always Check)
-
 Use \`hive_status()\` to see **runnable** tasks (dependencies satisfied) and **blockedBy** info.
 - Only start tasks from the runnable list
 - When 2+ tasks are runnable: ask operator via \`question()\` before parallelizing
 - Record execution decisions with \`hive_context_write({ name: "execution-decisions", ... })\`
 
 ### When to Load Skills
-
 - Multiple independent tasks → \`hive_skill("dispatching-parallel-agents")\`
 - Executing step-by-step → \`hive_skill("executing-plans")\`
 
 ### Delegation Check
-
 1. Is there a specialized agent?
 2. Does this need external data? → Scout
-3. Default: DELEGATE (don't do yourself)
+3. Default: delegate (don't do yourself)
 
 ### Worker Spawning
-
 \`\`\`
 hive_worktree_create({ task: "01-task-name" })  // Creates worktree + Forager
 \`\`\`
 
 ### After Delegation
-
-1. \`task()\` is BLOCKING — when it returns, the worker is DONE
+1. \`task()\` is blocking — when it returns, the worker is done
 2. Immediately call \`hive_status()\` to check the new task state and find next runnable tasks
-3. If task status is blocked: read blocker info → \`question()\` → user decision → resume with \`continueFrom: "blocked"\`
-4. Do NOT wait for notifications or poll — the result is already available when \`task()\` returns
-
-### Failure Recovery
-
-3 failures on same task → revert → ask user
+3. The delegated task MUST transition out of \`in_progress\`; if still \`in_progress\`, resume worker with explicit instruction to resolve commit response and retry
+4. If task status is blocked: read blocker info → \`question()\` → user decision → resume with \`continueFrom: "blocked"\`
+5. Skip polling — the result is available when \`task()\` returns
+
+### Batch Merge + Verify Workflow
+When multiple tasks are in flight, prefer **batch completion** over per-task verification:
+1. Dispatch a batch of runnable tasks (ask user before parallelizing).
+2. Wait for all workers to finish.
+3. Merge each completed task branch into the current branch.
+4. Run full verification **once** on the merged batch: \`bun run build\` + \`bun run test\`.
+5. If verification fails, diagnose with full context. Fix directly or re-dispatch targeted tasks as needed.
+
+### Failure Recovery (After 3 Consecutive Failures)
+1. Stop all further edits
+2. Revert to last known working state
+3. Document what was attempted
+4. Ask user via question() — present options and context
 
 ### Merge Strategy
-
-\`hive_merge({ task: "01-task-name" })\` after verification
+\`hive_merge({ task: "01-task-name" })\` for each task after the batch completes, then verify the batch
 
 ### Post-Batch Review (Hygienic)
-
 After completing and merging a batch:
 1. Ask the user via \`question()\` if they want a Hygienic code review for the batch.
 2. If yes, run \`task({ subagent_type: "hygienic", prompt: "Review implementation changes from the latest batch." })\`.
 3. Apply feedback before starting the next batch.
 
-### Orchestration Iron Laws
+### AGENTS.md Maintenance
+After feature completion (all tasks merged):
+1. Sync context findings to AGENTS.md: \`hive_agents_md({ action: "sync", feature: "feature-name" })\`
+2. Review the proposed diff with the user
+3. Apply approved changes to keep AGENTS.md current
+
+For projects without AGENTS.md:
+- Bootstrap with \`hive_agents_md({ action: "init" })\`
+- Generates initial documentation from codebase analysis
 
+### Orchestration Iron Laws
 - Delegate by default
 - Verify all work completes
-- Use \`question()\` for user input (NEVER plain text)
+- Use \`question()\` for user input (never plain text)
 
 ---
 
 ## Iron Laws (Both Phases)
-
 **Always:**
-- Detect phase FIRST via hive_status
-- Follow ONLY the active phase section
+- Detect phase first via hive_status
+- Follow the active phase section
 - Delegate research to Scout, implementation to Forager
 - Ask user before consulting Hygienic (Consultant/Reviewer/Debugger)
 - Load skills on-demand, one at a time
 
-**Never:**
+Investigate before acting: read referenced files before making claims about them.
+
+### Hard Blocks
+
+Do not violate:
 - Skip phase detection
 - Mix planning and orchestration in same action
 - Auto-load all skills at start
 
-**User Input:** ALWAYS use \`question()\` tool for any user input - NEVER ask questions via plain text. This ensures structured responses.
+### Anti-Patterns
+
+Blocking violations:
+- Ending a turn without a next action
+- Asking for user input in plain text instead of question()
+
+**User Input:** Use \`question()\` tool for any user input — structured prompts get structured responses. Plain text questions are easily missed or misinterpreted.
 `;
 
 // src/agents/architect.ts
@@ -14477,25 +15061,38 @@ PLANNER, NOT IMPLEMENTER. "Do X" means "create plan for X".
 
 ## Intent Classification (First)
 
-| Intent | Signals | Action |
-|--------|---------|--------|
-| Trivial | Single file, <10 lines | Do directly. No plan needed. |
-| Simple | 1-2 files, <30 min | Light interview → quick plan |
-| Complex | 3+ files, review needed | Full discovery → detailed plan |
-| Refactor | Existing code changes | Safety: tests, rollback, blast radius |
-| Greenfield | New feature | Research patterns BEFORE asking. Delegate to Scout via \`task({ subagent_type: "scout-researcher", prompt: "..." })\` for single investigations. |
+| Intent | Signals | Strategy | Action |
+|--------|---------|----------|--------|
+| Trivial | Single file, <10 lines | N/A | Do directly. No plan needed. |
+| Simple | 1-2 files, <30 min | Quick assessment | Light interview → quick plan |
+| Complex | 3+ files, review needed | Full discovery | Full discovery → detailed plan |
+| Refactor | Existing code changes | Safety-first: behavior preservation | Tests → blast radius → plan |
+| Greenfield | New feature | Discovery-first: explore before asking | Research → interview → plan |
+| Architecture | Cross-cutting, multi-system | Strategic: consult Scout | Deep research → plan |
 
 During Planning, use \`task({ subagent_type: "scout-researcher", ... })\` for exploration (BLOCKING — returns when done). For parallel exploration, issue multiple \`task()\` calls in the same message.
 
 ## Self-Clearance Check (After Every Exchange)
 
-□ Core objective clear?
-□ Scope defined (IN/OUT)?
-□ No critical ambiguities?
-□ Approach decided?
+□ Core objective clearly defined?
+□ Scope boundaries established (IN/OUT)?
+□ No critical ambiguities remaining?
+□ Technical approach decided?
+□ Test strategy confirmed (TDD/tests-after/none)?
+□ No blocking questions outstanding?
+
+ALL YES → Announce "Requirements clear. Generating plan." → Write plan
+ANY NO → Ask the specific unclear thing
+
+## Test Strategy (Ask Before Planning)
+
+For Build and Refactor intents, ASK:
+"Should this include automated tests?"
+- TDD: Red-Green-Refactor per task
+- Tests after: Add test tasks after implementation
+- None: No unit/integration tests
 
-ALL YES → Write plan
-ANY NO → Ask the unclear thing
+Record decision in draft. Embed in plan tasks.
 
 ## AI-Slop Flags
 
@@ -14515,6 +15112,18 @@ ANY NO → Ask the unclear thing
 | MINOR | FIX silently, note in summary |
 | AMBIGUOUS | Apply default, DISCLOSE in summary |
 
+## Turn Termination
+
+Valid endings:
+- Question to user (via question() tool)
+- Draft update + next question
+- Auto-transition to plan generation
+
+NEVER end with:
+- "Let me know if you have questions"
+- Summary without follow-up action
+- "When you're ready..."
+
 ## Draft as Working Memory
 
 Create draft on first exchange. Update after EVERY user response:
@@ -14583,28 +15192,18 @@ Delegate by default. Work yourself only when trivial.
 | Open-ended | "Improve", "Refactor" | Assess first, then delegate |
 | Ambiguous | Unclear scope | Ask ONE clarifying question |
 
-## Delegation Check (Before Acting)
+Intent Verbalization: "I detect [type] intent — [reason]. Routing to [action]."
 
-### Task Dependencies (Always Check)
-
-Use \`hive_status()\` to see **runnable** tasks (dependencies satisfied) and **blockedBy** info.
-- Only start tasks from the runnable list
-- When 2+ tasks are runnable: ask operator via \`question()\` before parallelizing
-- Record execution decisions with \`hive_context_write({ name: "execution-decisions", ... })\`
-
-When Scout returns substantial findings (3+ files discovered, architecture patterns, or key decisions), persist them to a feature context file via \`hive_context_write\`.
+## Delegation Check (Before Acting)
 
-If tasks are missing **Depends on** metadata, ask the planner to revise the plan before executing.
+Use \`hive_status()\` to see runnable tasks and blockedBy info. Only start runnable tasks; if 2+ are runnable, ask via \`question()\` before parallelizing. Record execution decisions with \`hive_context_write({ name: "execution-decisions", ... })\`. If tasks lack **Depends on** metadata, ask the planner to revise. If Scout returns substantial findings (3+ files, architecture patterns, or key decisions), persist them via \`hive_context_write\`.
 
-### Standard Checks
+Standard checks: specialized agent? can I do it myself for sure? external system data (DBs/APIs/3rd-party tools)? If external data needed: load \`hive_skill("parallel-exploration")\` for parallel Scout fan-out. In task mode, use task() for research fan-out. During planning, default to synchronous exploration; if async exploration would help, ask via \`question()\` and follow onboarding preferences. Default: delegate. Research tools (grep_app, context7, websearch, ast_grep) — delegate to Scout, not direct use.
 
-1. Is there a specialized agent that matches?
-2. Can I do it myself FOR SURE? REALLY?
-3. Does this require external system data (DBs/APIs/3rd-party tools)?
-→ If external data needed: Load \`hive_skill("parallel-exploration")\` for parallel Scout fan-out
-In task mode, use task() for research fan-out.
-During Planning, default to synchronous exploration. If async exploration would help, ask the user via \`question()\` and follow the onboarding preferences.
-→ Default: DELEGATE
+**When NOT to delegate:**
+- Single-file, <10-line changes — do directly
+- Sequential operations where you need the result of step N for step N+1
+- Questions answerable with one grep + one file read
 
 ## Delegation Prompt Structure (All 6 Sections)
 
@@ -14612,8 +15211,8 @@ During Planning, default to synchronous exploration. If async exploration would
 1. TASK: Atomic, specific goal
 2. EXPECTED OUTCOME: Concrete deliverables
 3. REQUIRED TOOLS: Explicit tool whitelist
-4. MUST DO: Exhaustive requirements
-5. MUST NOT DO: Forbidden actions
+4. REQUIRED: Exhaustive requirements
+5. FORBIDDEN: Forbidden actions
 6. CONTEXT: File paths, patterns, constraints
 \`\`\`
 
@@ -14626,31 +15225,45 @@ hive_worktree_create({ task: "01-task-name" })
 // In task mode, use task() for research fan-out.
 \`\`\`
 
-**Delegation Guidance:**
+Delegation guidance:
 - \`task()\` is BLOCKING — returns when the worker is done
 - Call \`hive_status()\` immediately after to check new state and find next runnable tasks
+- Invariant: delegated task must not remain \`in_progress\`; if it does, treat as non-terminal completion and resume/retry worker with explicit commit-result handling
 - For parallel fan-out, issue multiple \`task()\` calls in the same message
 
-## After Delegation - ALWAYS VERIFY
+## After Delegation - VERIFY
 
-- Does it work as expected?
-- Followed existing codebase pattern?
-- Followed MUST DO and MUST NOT DO?
+Your confidence ≈ 50% accurate. Always:
+- Read changed files (don’t trust self-reports)
+- Run lsp_diagnostics on modified files
+- Check acceptance criteria from spec
+
+Then confirm:
+- Works as expected
+- Follows codebase patterns
+- Meets requirements
+- No unintended side effects
+
+After completing and merging a batch, run full verification on the main branch: \`bun run build\`, \`bun run test\`. If failures occur, diagnose and fix or re-dispatch impacted tasks.
+
+## Search Stop Conditions
+
+- Stop when there is enough context
+- Stop when info repeats
+- Stop after 2 rounds with no new data
+- Stop when a direct answer is found
+- If still unclear, delegate or ask one focused question
 
 ## Blocker Handling
 
-When worker reports blocked:
-1. \`hive_status()\` — read blocker info
-2. \`question()\` — ask user (NEVER plain text)
-3. \`hive_worktree_create({ task, continueFrom: "blocked", decision })\`
+When worker reports blocked: \`hive_status()\` → read blocker info; \`question()\` → ask user (no plain text); \`hive_worktree_create({ task, continueFrom: "blocked", decision })\`.
 
 ## Failure Recovery (After 3 Consecutive Failures)
 
-1. STOP all further edits
-2. REVERT to last known working state
-3. DOCUMENT what was attempted
-4. Consult: \`task({ subagent_type: "oracle", prompt: "Analyze..." })\`
-5. If Oracle cannot resolve → ASK USER
+1. Stop all further edits
+2. Revert to last known working state
+3. Document what was attempted
+4. Ask user via question() — present options and context
 
 ## Merge Strategy
 
@@ -14658,37 +15271,39 @@ When worker reports blocked:
 hive_merge({ task: "01-task-name", strategy: "merge" })
 \`\`\`
 
-Merge only after verification passes.
+Merge after batch completes, then verify the merged result.
 
-## Post-Batch Review (Hygienic)
+### Post-Batch Review (Hygienic)
 
-After completing and merging a batch:
-1. Ask the user via \`question()\` if they want a Hygienic code review for the batch.
-2. If yes, run \`task({ subagent_type: "hygienic", prompt: "Review implementation changes from the latest batch." })\`.
-3. Apply feedback before starting the next batch.
+After completing and merging a batch: ask via \`question()\` if they want a Hygienic review. If yes, run \`task({ subagent_type: "hygienic", prompt: "Review implementation changes from the latest batch." })\` and apply feedback before the next batch.
 
-## Iron Laws
+### AGENTS.md Maintenance
 
-**Never:**
-- Work alone when specialists available
-- Skip delegation check
-- Skip verification after delegation
-- Continue after 3 failures without consulting
+After feature completion (all tasks merged): sync context findings to AGENTS.md via \`hive_agents_md({ action: "sync", feature: "feature-name" })\`, review the diff with the user, then apply approved changes.
 
-**Always:**
-- Classify intent FIRST
-- Delegate by default
-- Verify delegate work
-- Use question() for user input (NEVER plain text)
-- Cancel background tasks only when stale or no longer needed
+For quality review of AGENTS.md content, load \`hive_skill("agents-md-mastery")\`.
 
-**User Input:** ALWAYS use \`question()\` tool for any user input - NEVER ask questions via plain text. This ensures structured responses.
+For projects without AGENTS.md:
+- Bootstrap with \`hive_agents_md({ action: "init" })\`
+- Generates initial documentation from codebase analysis
+
+## Turn Termination
+
+Valid endings: worker delegation (hive_worktree_create), status check (hive_status), user question (question()), merge (hive_merge).
+Avoid ending with: "Let me know when you're ready", "When you're ready...", summary without next action, or waiting for something unspecified.
+
+## Guardrails
+
+Avoid: working alone when specialists are available; skipping delegation checks; skipping verification after delegation; continuing after 3 failures without consulting.
+Do: classify intent first; delegate by default; verify delegated work; use \`question()\` for user input (no plain text); cancel background tasks only when stale or no longer needed.
+Cancel background tasks only when stale or no longer needed.
+User input: use \`question()\` tool for any user input to ensure structured responses.
 `;
 
 // src/agents/scout.ts
 var SCOUT_BEE_PROMPT = `# Scout (Explorer/Researcher/Retrieval)
 
-Research BEFORE answering. Parallel execution by default.
+Research before answering; parallelize tool calls when investigating multiple independent questions.
 
 ## Request Classification
 
@@ -14711,18 +15326,13 @@ Success Looks Like: [concrete outcome]
 </analysis>
 \`\`\`
 
-### Phase 2: Parallel Execution (Default)
+### Phase 2: Parallel Execution
 
-ALWAYS run 3+ tools simultaneously:
+When investigating multiple independent questions, run related tools in parallel:
 \`\`\`
-// CORRECT: Parallel
 glob({ pattern: "**/*.ts" })
 grep({ pattern: "UserService" })
 context7_query-docs({ query: "..." })
-
-// WRONG: Sequential
-result1 = glob(...)
-result2 = grep(...)  // Wait for result1? NO!
 \`\`\`
 
 ### Phase 3: Structured Results
@@ -14741,12 +15351,29 @@ result2 = grep(...)  // Wait for result1? NO!
 </results>
 \`\`\`
 
+## Search Stop Conditions (After Research Protocol)
+
+Stop when any is true:
+- enough context to answer
+- repeated information across sources
+- two rounds with no new data
+- a direct answer is found
+
+## Evidence Check (Before Answering)
+
+- Every claim has a source (file:line, URL, snippet)
+- Avoid speculation; say "can't answer with available evidence" when needed
+
+## Investigate Before Answering
+
+- Read files before making claims about them
+
 ## Tool Strategy
 
 | Need | Tool |
 |------|------|
 | Type/Symbol info | LSP (goto_definition, find_references) |
-| Structural patterns | ast_grep_search |
+| Structural patterns | ast_grep_find_code |
 | Text patterns | grep |
 | File discovery | glob |
 | Git history | bash (git log, git blame) |
@@ -14756,19 +15383,11 @@ result2 = grep(...)  // Wait for result1? NO!
 
 ## External System Data (DB/API/3rd-party)
 
-When asked to retrieve raw data from external systems (MongoDB/Stripe/etc.):
-- Prefer targeted queries over broad dumps
-- Summarize findings; avoid flooding the orchestrator with raw records
+When asked to retrieve raw data from external systems:
+- Prefer targeted queries
+- Summarize findings; avoid raw dumps
 - Redact secrets and personal data
-- Provide minimal evidence and a concise summary
-- Note any access limitations or missing context
-
-## Documentation Discovery (External)
-
-1. \`websearch("library-name official documentation")\`
-2. Version check if specified
-3. Sitemap: \`webfetch(docs_url + "/sitemap.xml")\`
-4. Targeted fetch from sitemap
+- Note access limitations or missing context
 
 ## Evidence Format
 
@@ -14778,167 +15397,123 @@ When asked to retrieve raw data from external systems (MongoDB/Stripe/etc.):
 
 ## Persistence
 
-When operating within a feature context (background task with feature parameter):
-- If findings are substantial (3+ files discovered, architecture patterns, or key decisions):
-  Use \`hive_context_write\` to persist findings:
+When operating within a feature context:
+- If findings are substantial (3+ files, architecture patterns, or key decisions):
   \`\`\`
   hive_context_write({
-    name: "research-{topic-slug}",
-    content: "## Research: {Topic}
-
-Date: {date}
-
-## Context
-
-## research-findings
-
-# Research Findings for Hive Improvements v2
-
-## Worker Prompt Builder (\`worker-prompt.ts:48\`)
-- \`buildWorkerPrompt(params: WorkerPromptParams): string\`
-- Receives: feature, task, taskOrder, worktreePath, branch, plan, contextFiles, spec, previousTasks, continueFrom
-- Only uses: feature, task, taskOrder, worktreePath, branch, spec, continueFrom
-- plan/contextFiles/previousTasks passed but NOT used (already embedded in spec)
-- 10 sections: Assignment, Continuation(optional), Mission(=spec), Blocker Protocol, Completion Protocol, TDD, Debugging, Tools, Guidelines, User Input
-- **ZERO task-type awareness** — all workers get identical protocols
-- Budget: 100KB soft limit (advisory, not enforced)
-
-## Task Completion Flow (\`index.ts:974-1088\`)
-- \`hive_exec_complete\` accepts: task, summary (string), status (completed|blocked|failed|partial), blocker (optional)
-- Summary stored in: status.json, report.md, commit message (first 50 chars)
-- **Summary is free-form string** — no structure enforced
-- Completed summaries collected for next task: \`allTasks.filter(t => t.status === 'done' && t.summary)\`
-- Injected into spec as \`## Completed Tasks\` → \`- taskName: summary\`
-
-## TaskService (\`taskService.ts\`)
-- \`buildSpecContent()\` (lines 168-225): builds spec with Dependencies, Plan Section, Context, Completed Tasks
-- \`parseTasksFromPlan()\` (lines 532-602): regex \`/^###\\s+(\\d+)\\.\\s+(.+)$/\` for task headers
-- \`resolveDependencies()\` (lines 248-268): explicit deps or implicit sequential (N depends on N-1)
-- Types: TaskStatus has \`summary?: string\`, TaskInfo has \`summary?: string\`
-
-## Forager Agent (\`forager.ts:8-117\`)
-- Execution flow: Understand → Implement → Verify → Report
-- **NO orient/pre-flight phase** — jumps straight to understanding task spec
-- Can read codebase, use research tools (grep_app, context7, ast_grep)
-- Cannot: delegate (task/hive_exec_start), modify plan, use hive_merge
-- Notepads: \`.hive/features/{feature}/notepads/{learnings,issues,decisions}.md\` (append-only)
-
-## Hygienic Agent (\`hygienic.ts:8-105\`)
-- Reviews plan DOCUMENTATION quality, not design
-- 4 criteria: Clarity, Verifiability, Completeness, Big Picture
-- Verdict: OKAY or REJECT with 4-category assessment
-- When asked to review implementation → loads \`hive_skill("code-reviewer")\`
-- **Currently only invoked for plan review** (from Hive and Architect agents)
-- Cannot delegate/spawn workers
-
-## Scout Agent (\`scout.ts:8-112\`)
-- Read-only research agent
-- Classifies requests: CONCEPTUAL, IMPLEMENTATION, CODEBASE, COMPREHENSIVE
-- Output format: \`<results><files>...<answer>...<next_steps>...</results>\`
-- **Does NOT persist findings** — returns to orchestrator only
-- Parallel execution by default (3+ tools simultaneously)
-
-## Code-Reviewer Skill (\`skills/code-reviewer/SKILL.md\`)
-- Loaded by Hygienic when reviewing implementation
-- Output: APPROVE | REQUEST_CHANGES | NEEDS_DISCUSSION
-- Reviews: plan adherence, correctness, simplicity/YAGNI, risk
-- Already exists but underused (Hygienic only loads it when explicitly asked)
-
-## Plan Format
-- Headers: \`### N. Task Name\`
-- Sections: Depends on, What to do, Must NOT do, References (file:lines), Acceptance Criteria
-- Dependencies: \`none\` | \`1\` | \`1,3\` | implicit sequential
-
-## Skills (10 total)
-writing-plans, executing-plans, dispatching-parallel-agents, parallel-exploration, code-reviewer, onboarding, brainstorming, verification-before-completion, test-driven-development, systematic-debugging
-
-## Notepad System
-- Location: \`.hive/features/{feature}/notepads/{learnings,issues,decisions}.md\`
-- Workers append-only
-- **NOT automatically injected into next batch** — context injection only reads from \`contexts/\` directory"
+    name: "research-{topic}",
+    content: "## {Topic}\\n\\nDate: {YYYY-MM-DD}\\n\\n## Context\\n\\n## Findings"
   })
   \`\`\`
 
-## Iron Laws
-
-**Never:**
-- Create, modify, or delete files (read-only)
-- Answer without research first
-- Execute tools sequentially when parallel possible
-- Skip intent analysis
+## Operating Rules
 
-**Always:**
-- Classify request FIRST
-- Run 3+ tools in parallel
-- All paths MUST be absolute
+- Read-only behavior (no file changes)
+- Classify request first, then research
+- Use absolute paths for file references
 - Cite evidence for every claim
-- Use current year (2026) in web searches
+- Use the current year when reasoning about time-sensitive information
 `;
 
 // src/agents/forager.ts
 var FORAGER_BEE_PROMPT = `# Forager (Worker/Coder)
 
-Execute directly. NEVER delegate implementation. Work in isolation.
+You are an autonomous senior engineer. Once given direction, gather context, implement, and verify without waiting for prompts.
+
+Execute directly. Work in isolation. Do not delegate implementation.
 
-## Blocked Tools
+## Intent Extraction
 
-These tools are FORBIDDEN:
-- \`task\` — Orchestrator's job
-- \`hive_worktree_create\` — You ARE the spawned worker
-- \`hive_merge\` — Orchestrator's job
+| Spec says | True intent | Action |
+|---|---|---|
+| "Implement X" | Build + verify | Code → verify |
+| "Fix Y" | Root cause + minimal fix | Diagnose → fix → verify |
+| "Refactor Z" | Preserve behavior | Restructure → verify no regressions |
+| "Add tests" | Coverage | Write tests → verify |
+
+## Action Bias
+
+- Act directly: implement first, explain in commit summary. Complete all steps before reporting.
+- REQUIRED: keep going until done, make decisions, course-correct on failure
+
+Your tool access is scoped to your role. Use only the tools available to you.
 
 ## Allowed Research
 
 CAN use for quick lookups:
 - \`grep_app_searchGitHub\` — OSS patterns
 - \`context7_query-docs\` — Library docs
-- \`ast_grep_search\` — AST patterns
+- \`ast_grep_find_code_by_rule\` — AST patterns
+- \`ast_grep_scan-code\` — Code quality scan (best-effort verification)
+- \`ast_grep_find_code\` — Find code patterns (best-effort verification)
 - \`glob\`, \`grep\`, \`read\` — Codebase exploration
 
+## Resolve Before Blocking
+
+Default to exploration, questions are LAST resort.
+Context inference: Before asking "what does X do?", READ X first.
+
+Apply in order before reporting as blocked:
+1. Read the referenced files and surrounding code
+2. Search for similar patterns in the codebase
+3. Check docs via research tools
+4. Try a reasonable approach
+5. Last resort: report blocked
+
+Investigate before acting. Do not speculate about code you have not read.
+
 ## Plan = READ ONLY
 
-CRITICAL: NEVER MODIFY THE PLAN FILE
-- May READ to understand task
-- MUST NOT edit, modify, or update plan
-- Only Orchestrator (Swarm) manages plan
+Do not modify the plan file.
+- Read to understand the task
+- Only the orchestrator manages plan updates
 
 ## Persistent Notes
 
-For substantial discoveries (architecture patterns, key decisions, gotchas that affect multiple tasks):
-Use \`hive_context_write({ name: "learnings", content: "..." })\` to persist for future workers.
+For substantial discoveries (architecture patterns, key decisions, gotchas that affect multiple tasks), use:
+\`hive_context_write({ name: "learnings", content: "..." })\`.
 
-## Execution Flow
+## Working Rules
 
-### 1. Understand Task
-Read spec for:
-- **What to do**
-- **References** (file:lines)
-- **Must NOT do** (guardrails)
-- **Acceptance criteria**
+- DRY/Search First: look for existing helpers before adding new code
+- Convention Following: check neighboring files and package.json, then follow existing patterns
+- Efficient Edits: read enough context before editing, batch logical edits
+- Tight Error Handling: avoid broad catches or silent defaults; propagate errors explicitly
+- Avoid Over-engineering: only implement what was asked for
+- Reversibility Preference: favor local, reversible actions; confirm before hard-to-reverse steps
+- Promise Discipline: do not commit to future work; if not done this turn, label it "Next steps"
+- No Comments: do not add comments unless the spec requests them
+- Concise Output: minimize output and avoid extra explanations unless asked
 
-### 2. Orient (Pre-flight Before Coding)
-Before writing code:
-- Confirm dependencies are satisfied and required context is present
-- Identify the exact files/sections to touch (from references)
-- Decide the first failing test you will write (TDD)
-- Plan the minimum change to reach green
+## Execution Loop (max 3 iterations)
 
-### 3. Implement
-Follow spec exactly. Use references for patterns.
+EXPLORE → PLAN → EXECUTE → VERIFY → LOOP
 
-\`\`\`
-read(file, { offset: line, limit: 30 })  // Check references
-edit(file, { old: "...", new: "..." })   // Implement
-bash("npm test")                          // Verify
-\`\`\`
+- EXPLORE: read references, gather context, search for patterns
+- PLAN: decide the minimum change, files to touch, and verification commands
+- EXECUTE: edit using conventions, reuse helpers, batch changes
+- VERIFY: run best-effort checks (tests if available, ast_grep, lsp_diagnostics)
+- LOOP: if verification fails, diagnose and retry within the limit
+
+## Progress Updates
+
+Provide brief status at meaningful milestones.
+
+## Completion Checklist
+
+- All acceptance criteria met?
+- Best-effort verification done and recorded?
+- Re-read the spec — missed anything?
+- Said "I'll do X" — did you?
+- Plan closure: mark each intention as Done, Blocked, or Cancelled
+- Record exact commands and results
 
-### 4. Verify
-Run acceptance criteria:
-- Tests pass
-- Build succeeds
-- lsp_diagnostics clean on changed files
+## Failure Recovery
+
+If 3 different approaches fail: stop edits, revert local changes, document attempts, report blocked.
+If you have tried 3 approaches and still cannot finish safely, report as blocked.
 
-### 5. Report
+## Reporting
 
 **Success:**
 \`\`\`
@@ -14949,7 +15524,9 @@ hive_worktree_commit({
 })
 \`\`\`
 
-**CRITICAL: After hive_worktree_commit, STOP IMMEDIATELY.**
+Then inspect the tool response fields:
+- If \`ok=true\` and \`terminal=true\`: stop and hand off to orchestrator
+- If \`ok=false\` or \`terminal=false\`: DO NOT STOP. Follow \`nextAction\`, remediate, and retry \`hive_worktree_commit\`
 
 **Blocked (need user decision):**
 \`\`\`
@@ -14966,28 +15543,11 @@ hive_worktree_commit({
 })
 \`\`\`
 
-## Failure Recovery
-
-After 3 consecutive failures:
-1. STOP all further edits
-2. Document what was tried
-3. Report as blocked with options
-
-## Iron Laws
-
-**Never:**
-- Exceed task scope
-- Modify plan file
-- Use \`task\` or \`hive_worktree_create\`
-- Continue after hive_worktree_commit
-- Skip verification
+## Docker Sandbox
 
-**Always:**
-- Follow references for patterns
-- Run acceptance criteria
-- Report blockers with options
-- APPEND to notepads (never overwrite)
-- lsp_diagnostics before reporting done
+When sandbox mode is active, bash commands run inside Docker; file edits still apply to the host worktree.
+If a command must run on the host or Docker is missing, report blocked.
+For deeper Docker expertise, load \`hive_skill("docker-mastery")\`.
 `;
 
 // src/agents/hygienic.ts
@@ -15017,7 +15577,10 @@ Self-check before every critique:
 
 ### 2. Verification & Acceptance Criteria
 - Are criteria measurable and concrete?
-- Red flags: "should work", "looks good", "properly handles"
+- Are they agent-executable (tool-runnable) without human judgment?
+- Do they specify exact commands + expected signals (exit code, output text, counts)?
+- Red flags: "should work", "looks good", "properly handles", "verify manually"
+- If manual checks are required, the plan must explain why automation is impossible
 
 ### 3. Context Completeness (90% Confidence)
 - Could a capable worker execute with 90% confidence?
@@ -15149,20 +15712,39 @@ import * as fs8 from "fs";
 import * as path4 from "path";
 import * as fs10 from "fs";
 import * as path6 from "path";
+import * as fs11 from "fs";
+import * as path7 from "path";
+import { existsSync as existsSync5 } from "fs";
+import { join as join8, sep } from "path";
+import { execSync } from "child_process";
 var __create = Object.create;
 var __getProtoOf = Object.getPrototypeOf;
 var __defProp2 = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
 var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached2 = cache.get(mod);
+    if (cached2)
+      return cached2;
+  }
   target = mod != null ? __create(__getProtoOf(mod)) : {};
   const to = isNodeMode || !mod || !mod.__esModule ? __defProp2(target, "default", { value: mod, enumerable: true }) : target;
   for (let key of __getOwnPropNames(mod))
     if (!__hasOwnProp.call(to, key))
       __defProp2(to, key, {
-        get: () => mod[key],
+        get: __accessProp.bind(mod, key),
         enumerable: true
       });
+  if (canCache)
+    cache.set(mod, to);
   return to;
 };
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
@@ -15986,6 +16568,7 @@ var DEFAULT_HIVE_CONFIG = {
   disableSkills: [],
   disableMcps: [],
   agentMode: "unified",
+  sandbox: "none",
   agents: {
     "hive-master": {
       model: DEFAULT_AGENT_MODELS["hive-master"],
@@ -16136,12 +16719,14 @@ function isLockStale(lockPath, staleTTL) {
 function acquireLockSync(filePath, options = {}) {
   const opts = { ...DEFAULT_LOCK_OPTIONS, ...options };
   const lockPath = getLockPath(filePath);
+  const lockDir = path2.dirname(lockPath);
   const startTime = Date.now();
   const lockContent = JSON.stringify({
     pid: process.pid,
     timestamp: new Date().toISOString(),
     filePath
   });
+  ensureDir(lockDir);
   while (true) {
     try {
       const fd = fs2.openSync(lockPath, fs2.constants.O_CREAT | fs2.constants.O_EXCL | fs2.constants.O_WRONLY);
@@ -16154,15 +16739,18 @@ function acquireLockSync(filePath, options = {}) {
       };
     } catch (err) {
       const error45 = err;
-      if (error45.code !== "EEXIST") {
+      if (error45.code === "ENOENT") {
+        ensureDir(lockDir);
+      } else if (error45.code === "EEXIST") {
+        if (isLockStale(lockPath, opts.staleLockTTL)) {
+          try {
+            fs2.unlinkSync(lockPath);
+            continue;
+          } catch {}
+        }
+      } else {
         throw error45;
       }
-      if (isLockStale(lockPath, opts.staleLockTTL)) {
-        try {
-          fs2.unlinkSync(lockPath);
-          continue;
-        } catch {}
-      }
       if (Date.now() - startTime >= opts.timeout) {
         throw new Error(`Failed to acquire lock on ${filePath} after ${opts.timeout}ms. ` + `Lock file: ${lockPath}`);
       }
@@ -16187,14 +16775,6 @@ function writeAtomic(filePath, content) {
 function writeJsonAtomic(filePath, data) {
   writeAtomic(filePath, JSON.stringify(data, null, 2));
 }
-function writeJsonLockedSync(filePath, data, options = {}) {
-  const release = acquireLockSync(filePath, options);
-  try {
-    writeJsonAtomic(filePath, data);
-  } finally {
-    release();
-  }
-}
 function deepMerge(target, patch) {
   const result = { ...target };
   for (const key of Object.keys(patch)) {
@@ -16723,23 +17303,31 @@ ${f.content}`).join(`
   }
   update(featureName, taskFolder, updates, lockOptions) {
     const statusPath = getTaskStatusPath(this.projectRoot, featureName, taskFolder);
-    const current = readJson(statusPath);
-    if (!current) {
+    if (!fileExists(statusPath)) {
       throw new Error(`Task '${taskFolder}' not found`);
     }
-    const updated = {
-      ...current,
-      ...updates,
-      schemaVersion: TASK_STATUS_SCHEMA_VERSION
-    };
-    if (updates.status === "in_progress" && !current.startedAt) {
-      updated.startedAt = new Date().toISOString();
-    }
-    if (updates.status === "done" && !current.completedAt) {
-      updated.completedAt = new Date().toISOString();
+    const release = acquireLockSync(statusPath, lockOptions);
+    try {
+      const current = readJson(statusPath);
+      if (!current) {
+        throw new Error(`Task '${taskFolder}' not found`);
+      }
+      const updated = {
+        ...current,
+        ...updates,
+        schemaVersion: TASK_STATUS_SCHEMA_VERSION
+      };
+      if (updates.status === "in_progress" && !current.startedAt) {
+        updated.startedAt = new Date().toISOString();
+      }
+      if (updates.status === "done" && !current.completedAt) {
+        updated.completedAt = new Date().toISOString();
+      }
+      writeJsonAtomic(statusPath, updated);
+      return updated;
+    } finally {
+      release();
     }
-    writeJsonLockedSync(statusPath, updated, lockOptions);
-    return updated;
   }
   patchBackgroundFields(featureName, taskFolder, patch, lockOptions) {
     const statusPath = getTaskStatusPath(this.projectRoot, featureName, taskFolder);
@@ -21465,6 +22053,12 @@ class ContextService {
     ensureDir(contextPath);
     const filePath = path4.join(contextPath, this.normalizeFileName(fileName));
     writeText(filePath, content);
+    const totalChars = this.list(featureName).reduce((sum, c) => sum + c.content.length, 0);
+    if (totalChars > 20000) {
+      return `${filePath}
+
+⚠️ Context total: ${totalChars} chars (exceeds 20,000). Consider archiving older contexts with contextService.archive().`;
+    }
     return filePath;
   }
   read(featureName, fileName) {
@@ -21510,6 +22104,37 @@ ${f.content}`);
 
 `);
   }
+  archive(featureName) {
+    const contexts = this.list(featureName);
+    if (contexts.length === 0)
+      return { archived: [], archivePath: "" };
+    const contextPath = getContextPath(this.projectRoot, featureName);
+    const archiveDir = path4.join(contextPath, "..", "archive");
+    ensureDir(archiveDir);
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const archived = [];
+    for (const ctx of contexts) {
+      const archiveName = `${timestamp}_${ctx.name}.md`;
+      const src = path4.join(contextPath, `${ctx.name}.md`);
+      const dest = path4.join(archiveDir, archiveName);
+      fs8.copyFileSync(src, dest);
+      fs8.unlinkSync(src);
+      archived.push(ctx.name);
+    }
+    return { archived, archivePath: archiveDir };
+  }
+  stats(featureName) {
+    const contexts = this.list(featureName);
+    if (contexts.length === 0)
+      return { count: 0, totalChars: 0 };
+    const sorted2 = [...contexts].sort((a, b) => new Date(a.updatedAt).getTime() - new Date(b.updatedAt).getTime());
+    return {
+      count: contexts.length,
+      totalChars: contexts.reduce((sum, c) => sum + c.content.length, 0),
+      oldest: sorted2[0].name,
+      newest: sorted2[sorted2.length - 1].name
+    };
+  }
   normalizeFileName(name) {
     const normalized = name.replace(/\.md$/, "");
     return `${normalized}.md`;
@@ -21517,6 +22142,7 @@ ${f.content}`);
 }
 class ConfigService {
   configPath;
+  cachedConfig = null;
   constructor() {
     const homeDir = process.env.HOME || process.env.USERPROFILE || "";
     const configDir = path6.join(homeDir, ".config", "opencode");
@@ -21526,13 +22152,17 @@ class ConfigService {
     return this.configPath;
   }
   get() {
+    if (this.cachedConfig !== null) {
+      return this.cachedConfig;
+    }
     try {
       if (!fs10.existsSync(this.configPath)) {
-        return { ...DEFAULT_HIVE_CONFIG };
+        this.cachedConfig = { ...DEFAULT_HIVE_CONFIG };
+        return this.cachedConfig;
       }
       const raw = fs10.readFileSync(this.configPath, "utf-8");
       const stored = JSON.parse(raw);
-      return {
+      const merged = {
         ...DEFAULT_HIVE_CONFIG,
         ...stored,
         agents: {
@@ -21564,11 +22194,15 @@ class ConfigService {
           }
         }
       };
+      this.cachedConfig = merged;
+      return this.cachedConfig;
     } catch {
-      return { ...DEFAULT_HIVE_CONFIG };
+      this.cachedConfig = { ...DEFAULT_HIVE_CONFIG };
+      return this.cachedConfig;
     }
   }
   set(updates) {
+    this.cachedConfig = null;
     const current = this.get();
     const merged = {
       ...current,
@@ -21583,6 +22217,7 @@ class ConfigService {
       fs10.mkdirSync(configDir, { recursive: true });
     }
     fs10.writeFileSync(this.configPath, JSON.stringify(merged, null, 2));
+    this.cachedConfig = merged;
     return merged;
   }
   exists() {
@@ -21623,6 +22258,320 @@ class ConfigService {
     const config2 = this.get();
     return config2.disableMcps ?? [];
   }
+  getSandboxConfig() {
+    const config2 = this.get();
+    const mode = config2.sandbox ?? "none";
+    const image = config2.dockerImage;
+    const persistent = config2.persistentContainers ?? mode === "docker";
+    return { mode, ...image && { image }, persistent };
+  }
+  getHookCadence(hookName, options) {
+    const config2 = this.get();
+    const configuredCadence = config2.hook_cadence?.[hookName];
+    if (options?.safetyCritical && configuredCadence && configuredCadence > 1) {
+      console.warn(`[hive:cadence] Ignoring cadence > 1 for safety-critical hook: ${hookName}`);
+      return 1;
+    }
+    if (configuredCadence === undefined || configuredCadence === null) {
+      return 1;
+    }
+    if (configuredCadence <= 0 || !Number.isInteger(configuredCadence)) {
+      console.warn(`[hive:cadence] Invalid cadence ${configuredCadence} for ${hookName}, using 1`);
+      return 1;
+    }
+    return configuredCadence;
+  }
+}
+
+class AgentsMdService {
+  rootDir;
+  contextService;
+  constructor(rootDir, contextService) {
+    this.rootDir = rootDir;
+    this.contextService = contextService;
+  }
+  async init() {
+    const agentsMdPath = path7.join(this.rootDir, "AGENTS.md");
+    const existed = fileExists(agentsMdPath);
+    if (existed) {
+      const existing = readText(agentsMdPath);
+      return { content: existing || "", existed: true };
+    }
+    const content = await this.scanAndGenerate();
+    return { content, existed: false };
+  }
+  async sync(featureName) {
+    const contexts = this.contextService.list(featureName);
+    const agentsMdPath = path7.join(this.rootDir, "AGENTS.md");
+    const current = await fs11.promises.readFile(agentsMdPath, "utf-8").catch(() => "");
+    const findings = this.extractFindings(contexts);
+    const proposals = this.generateProposals(findings, current);
+    return { proposals, diff: this.formatDiff(current, proposals) };
+  }
+  apply(content) {
+    const agentsMdPath = path7.join(this.rootDir, "AGENTS.md");
+    const isNew = !fileExists(agentsMdPath);
+    writeText(agentsMdPath, content);
+    return { path: agentsMdPath, chars: content.length, isNew };
+  }
+  extractFindings(contexts) {
+    const findings = [];
+    const patterns = [
+      /we\s+use\s+[^.\n]+/gi,
+      /prefer\s+[^.\n]+\s+over\s+[^.\n]+/gi,
+      /don't\s+use\s+[^.\n]+/gi,
+      /do\s+not\s+use\s+[^.\n]+/gi,
+      /(?:build|test|dev)\s+command:\s*[^.\n]+/gi,
+      /[a-zA-Z]+\s+lives?\s+in\s+\/[^\s.\n]+/gi
+    ];
+    for (const context of contexts) {
+      const lines = context.content.split(`
+`);
+      for (const line of lines) {
+        const trimmed2 = line.trim();
+        if (!trimmed2 || trimmed2.startsWith("#"))
+          continue;
+        for (const pattern of patterns) {
+          const matches = trimmed2.match(pattern);
+          if (matches) {
+            for (const match of matches) {
+              const finding = match.trim();
+              if (finding && !findings.includes(finding)) {
+                findings.push(finding);
+              }
+            }
+          }
+        }
+      }
+    }
+    return findings;
+  }
+  generateProposals(findings, current) {
+    const proposals = [];
+    const currentLower = current.toLowerCase();
+    for (const finding of findings) {
+      const findingLower = finding.toLowerCase();
+      if (!currentLower.includes(findingLower)) {
+        proposals.push(finding);
+      }
+    }
+    return proposals;
+  }
+  formatDiff(current, proposals) {
+    if (proposals.length === 0)
+      return "";
+    const lines = proposals.map((p) => `+ ${p}`);
+    return lines.join(`
+`);
+  }
+  async scanAndGenerate() {
+    const detections = await this.detectProjectInfo();
+    return this.generateTemplate(detections);
+  }
+  async detectProjectInfo() {
+    const packageJsonPath = path7.join(this.rootDir, "package.json");
+    let packageJson = null;
+    if (fileExists(packageJsonPath)) {
+      try {
+        const content = readText(packageJsonPath);
+        packageJson = content ? JSON.parse(content) : null;
+      } catch {}
+    }
+    const info = {
+      packageManager: this.detectPackageManager(),
+      language: this.detectLanguage(),
+      testFramework: this.detectTestFramework(packageJson),
+      buildCommand: packageJson?.scripts?.build || null,
+      testCommand: packageJson?.scripts?.test || null,
+      devCommand: packageJson?.scripts?.dev || null,
+      isMonorepo: this.detectMonorepo(packageJson)
+    };
+    return info;
+  }
+  detectPackageManager() {
+    if (fileExists(path7.join(this.rootDir, "bun.lockb")))
+      return "bun";
+    if (fileExists(path7.join(this.rootDir, "pnpm-lock.yaml")))
+      return "pnpm";
+    if (fileExists(path7.join(this.rootDir, "yarn.lock")))
+      return "yarn";
+    if (fileExists(path7.join(this.rootDir, "package-lock.json")))
+      return "npm";
+    return "npm";
+  }
+  detectLanguage() {
+    if (fileExists(path7.join(this.rootDir, "tsconfig.json")))
+      return "TypeScript";
+    if (fileExists(path7.join(this.rootDir, "package.json")))
+      return "JavaScript";
+    if (fileExists(path7.join(this.rootDir, "requirements.txt")))
+      return "Python";
+    if (fileExists(path7.join(this.rootDir, "go.mod")))
+      return "Go";
+    if (fileExists(path7.join(this.rootDir, "Cargo.toml")))
+      return "Rust";
+    return "Unknown";
+  }
+  detectTestFramework(packageJson) {
+    if (!packageJson)
+      return null;
+    const deps = {
+      ...packageJson.dependencies,
+      ...packageJson.devDependencies
+    };
+    if (deps?.vitest)
+      return "vitest";
+    if (deps?.jest)
+      return "jest";
+    if (this.detectPackageManager() === "bun")
+      return "bun test";
+    if (deps?.pytest)
+      return "pytest";
+    return null;
+  }
+  detectMonorepo(packageJson) {
+    if (!packageJson)
+      return false;
+    return !!packageJson.workspaces;
+  }
+  generateTemplate(info) {
+    const sections = [];
+    sections.push(`# Agent Guidelines
+`);
+    sections.push(`## Overview
+`);
+    sections.push(`This project uses AI-assisted development. Follow these guidelines.
+`);
+    sections.push(`## Build & Test Commands
+`);
+    sections.push("```bash");
+    if (info.isMonorepo) {
+      sections.push("# This is a monorepo using bun workspaces");
+    }
+    if (info.buildCommand) {
+      sections.push(`# Build`);
+      sections.push(`${info.packageManager} run build`);
+      sections.push("");
+    }
+    if (info.testCommand) {
+      sections.push(`# Run tests`);
+      sections.push(`${info.packageManager} ${info.testCommand === "bun test" ? "test" : "run test"}`);
+      sections.push("");
+    }
+    if (info.devCommand) {
+      sections.push(`# Development mode`);
+      sections.push(`${info.packageManager} run dev`);
+    }
+    sections.push("```\n");
+    sections.push(`## Technology Stack
+`);
+    sections.push(`- **Language**: ${info.language}`);
+    sections.push(`- **Package Manager**: ${info.packageManager}`);
+    if (info.testFramework) {
+      sections.push(`- **Test Framework**: ${info.testFramework}`);
+    }
+    if (info.isMonorepo) {
+      sections.push(`- **Structure**: Monorepo with workspaces`);
+    }
+    sections.push("");
+    sections.push(`## Code Style
+`);
+    sections.push(`Follow existing patterns in the codebase.
+`);
+    sections.push(`## Architecture Principles
+`);
+    sections.push(`Document key architectural decisions here.
+`);
+    return sections.join(`
+`);
+  }
+}
+
+class DockerSandboxService {
+  static detectImage(worktreePath) {
+    if (existsSync5(join8(worktreePath, "Dockerfile"))) {
+      return null;
+    }
+    if (existsSync5(join8(worktreePath, "package.json"))) {
+      return "node:22-slim";
+    }
+    if (existsSync5(join8(worktreePath, "requirements.txt")) || existsSync5(join8(worktreePath, "pyproject.toml"))) {
+      return "python:3.12-slim";
+    }
+    if (existsSync5(join8(worktreePath, "go.mod"))) {
+      return "golang:1.22-slim";
+    }
+    if (existsSync5(join8(worktreePath, "Cargo.toml"))) {
+      return "rust:1.77-slim";
+    }
+    return "ubuntu:24.04";
+  }
+  static buildRunCommand(worktreePath, command, image) {
+    const escapedCommand = command.replace(/'/g, "'\\''");
+    return `docker run --rm -v ${worktreePath}:/app -w /app ${image} sh -c '${escapedCommand}'`;
+  }
+  static containerName(worktreePath) {
+    const parts = worktreePath.split(sep);
+    const worktreeIdx = parts.indexOf(".worktrees");
+    if (worktreeIdx === -1 || worktreeIdx + 2 >= parts.length) {
+      return `hive-sandbox-${Date.now()}`;
+    }
+    const feature = parts[worktreeIdx + 1];
+    const task = parts[worktreeIdx + 2];
+    const name = `hive-${feature}-${task}`.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+    return name.slice(0, 63);
+  }
+  static ensureContainer(worktreePath, image) {
+    const name = this.containerName(worktreePath);
+    try {
+      execSync(`docker inspect --format='{{.State.Running}}' ${name}`, { stdio: "pipe" });
+      return name;
+    } catch {
+      execSync(`docker run -d --name ${name} -v ${worktreePath}:/app -w /app ${image} tail -f /dev/null`, { stdio: "pipe" });
+      return name;
+    }
+  }
+  static buildExecCommand(containerName, command) {
+    const escapedCommand = command.replace(/'/g, "'\\''");
+    return `docker exec ${containerName} sh -c '${escapedCommand}'`;
+  }
+  static stopContainer(worktreePath) {
+    const name = this.containerName(worktreePath);
+    try {
+      execSync(`docker rm -f ${name}`, { stdio: "ignore" });
+    } catch {}
+  }
+  static isDockerAvailable() {
+    try {
+      execSync("docker info", { stdio: "ignore" });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  static wrapCommand(worktreePath, command, config2) {
+    if (command.startsWith("HOST: ")) {
+      return command.substring(6);
+    }
+    if (config2.mode === "none") {
+      return command;
+    }
+    let image;
+    if (config2.image) {
+      image = config2.image;
+    } else {
+      image = this.detectImage(worktreePath);
+      if (image === null) {
+        return command;
+      }
+    }
+    if (config2.persistent) {
+      const containerName = this.ensureContainer(worktreePath, image);
+      return this.buildExecCommand(containerName, command);
+    } else {
+      return this.buildRunCommand(worktreePath, command, image);
+    }
+  }
 }
 function computeRunnableAndBlocked(tasks) {
   const statusByFolder = new Map;
@@ -21788,8 +22737,16 @@ hive_worktree_commit({
 })
 \`\`\`
 
-**CRITICAL: After calling hive_worktree_commit, you MUST STOP IMMEDIATELY.**
-Do NOT continue working. Do NOT respond further. Your session is DONE.
+Then inspect the tool response fields:
+- If \`ok=true\` and \`terminal=true\`: stop the session
+- Otherwise: **DO NOT STOP**. Follow \`nextAction\`, remediate, and retry \`hive_worktree_commit\`
+
+**CRITICAL: Stop only on terminal commit result (ok=true and terminal=true).**
+If commit returns non-terminal (for example verification_required), DO NOT STOP.
+Follow result.nextAction, fix the issue, and call hive_worktree_commit again.
+
+Only when commit result is terminal should you stop.
+Do NOT continue working after a terminal result. Do NOT respond further. Your session is DONE.
 The Hive Master will take over from here.
 
 **Summary Guidance** (used verbatim for downstream task context):
@@ -22136,6 +23093,31 @@ function normalizeVariant(variant) {
   return trimmed2.length > 0 ? trimmed2 : undefined;
 }
 
+// src/hooks/system-hook.ts
+var fallbackTurnCounters = {};
+function shouldExecuteHook(hookName, configService, turnCounters, options) {
+  const cadence = configService?.getHookCadence(hookName, options) ?? 1;
+  const counters = turnCounters ?? fallbackTurnCounters;
+  counters[hookName] = (counters[hookName] || 0) + 1;
+  const currentTurn = counters[hookName];
+  if (cadence === 1) {
+    return true;
+  }
+  return (currentTurn - 1) % cadence === 0;
+}
+var HIVE_SYSTEM_PROMPT = `
+## Hive — Active Session
+
+**Important:** hive_worktree_commit commits to the task branch but does NOT merge.
+Use hive_merge to integrate changes into the current branch.
+`;
+
+// src/utils/compaction-prompt.ts
+var COMPACTION_RESUME_PROMPT = "You were compacted mid-task. " + "Resume by reading your worker-prompt.md (in the task worktree root) to recall your assignment. " + "Do not call status tools or re-read the full codebase. " + "Locate your last commit message or notes, then continue from where you left off.";
+function buildCompactionPrompt() {
+  return COMPACTION_RESUME_PROMPT;
+}
+
 // src/index.ts
 function formatSkillsXml(skills) {
   if (skills.length === 0)
@@ -22221,91 +23203,13 @@ No Hive skills available.` : base + formatSkillsXml(filteredSkills);
     }
   });
 }
-var HIVE_SYSTEM_PROMPT = `
-## Hive - Feature Development System
-
-Plan-first development: Write plan → User reviews → Approve → Execute tasks
-
-### Tools (14 total)
-
-| Domain | Tools |
-|--------|-------|
-| Feature | hive_feature_create, hive_feature_complete |
-| Plan | hive_plan_write, hive_plan_read, hive_plan_approve |
-| Task | hive_tasks_sync, hive_task_create, hive_task_update |
-| Worktree | hive_worktree_create, hive_worktree_commit, hive_worktree_discard |
-| Merge | hive_merge |
-| Context | hive_context_write |
-| Status | hive_status |
-| Skill | hive_skill |
-
-### Workflow
-
-1. \`hive_feature_create(name)\` - Create feature
-2. \`hive_plan_write(content)\` - Write plan.md
-3. User adds comments in VSCode → \`hive_plan_read\` to see them
-4. Revise plan → User approves
-5. \`hive_tasks_sync()\` - Generate tasks from plan
-6. \`hive_worktree_create(task)\` → work in worktree → \`hive_worktree_commit(task, summary)\`
-7. \`hive_merge(task)\` - Merge task branch into main (when ready)
-
-**Important:** \`hive_worktree_commit\` commits changes to task branch but does NOT merge.
-Use \`hive_merge\` to explicitly integrate changes. Worktrees persist until manually removed.
-
-### Delegated Execution
-
-\`hive_worktree_create\` creates worktree and spawns worker automatically:
-
-1. \`hive_worktree_create(task)\` → Creates worktree + spawns Forager (Worker/Coder) worker
-2. Worker executes → calls \`hive_worktree_commit(status: "completed")\`
-3. Worker blocked → calls \`hive_worktree_commit(status: "blocked", blocker: {...})\`
-
-**Handling blocked workers:**
-1. Check blockers with \`hive_status()\`
-2. Read the blocker info (reason, options, recommendation, context)
-3. Ask user via \`question()\` tool - NEVER plain text
-4. Resume with \`hive_worktree_create(task, continueFrom: "blocked", decision: answer)\`
-
-**CRITICAL**: When resuming, a NEW worker spawns in the SAME worktree.
-The previous worker's progress is preserved. Include the user's decision in the \`decision\` parameter.
-
-**After task() Returns:**
-- task() is BLOCKING — when it returns, the worker is DONE
-- Call \`hive_status()\` immediately to check the new task state and find next runnable tasks
-- No notifications or polling needed — the result is already available
-
-**For research**, use MCP tools or parallel exploration:
-- \`grep_app_searchGitHub\` - Find code in OSS
-- \`context7_query-docs\` - Library documentation
-- \`websearch_web_search_exa\` - Web search via Exa
-- \`ast_grep_search\` - AST-based search
-- For exploratory fan-out, load \`hive_skill("parallel-exploration")\` and use multiple \`task()\` calls in the same message
-
-### Planning Phase - Context Management REQUIRED
-
-As you research and plan, CONTINUOUSLY save findings using \`hive_context_write\`:
-- Research findings (API patterns, library docs, codebase structure)
-- User preferences ("we use Zustand, not Redux")
-- Rejected alternatives ("tried X, too complex")
-- Architecture decisions ("auth lives in /lib/auth")
-
-**Update existing context files** when new info emerges - dont create duplicates.
-
-\`hive_tasks_sync\` parses \`### N. Task Name\` headers.
-
-### Execution Phase - Stay Aligned
-
-During execution, call \`hive_status\` periodically to:
-- Check current progress and pending work
-- See context files to read
-- Get reminded of next actions
-`;
 var plugin = async (ctx) => {
   const { directory, client } = ctx;
   const featureService = new FeatureService(directory);
   const planService = new PlanService(directory);
   const taskService = new TaskService(directory);
   const contextService = new ContextService(directory);
+  const agentsMdService = new AgentsMdService(directory, contextService);
   const configService = new ConfigService;
   const disabledMcps = configService.getDisabledMcps();
   const disabledSkills = configService.getDisabledSkills();
@@ -22314,7 +23218,7 @@ var plugin = async (ctx) => {
   const effectiveAutoLoadSkills = configService.getAgentConfig("hive-master").autoLoadSkills ?? [];
   const worktreeService = new WorktreeService({
     baseDir: directory,
-    hiveDir: path7.join(directory, ".hive")
+    hiveDir: path8.join(directory, ".hive")
   });
   const isOmoSlimEnabled = () => {
     return configService.isOmoSlimEnabled();
@@ -22341,7 +23245,7 @@ var plugin = async (ctx) => {
   };
   const checkBlocked = (feature) => {
     const fs9 = __require("fs");
-    const blockedPath = path7.join(directory, ".hive", "features", feature, "BLOCKED");
+    const blockedPath = path8.join(directory, ".hive", "features", feature, "BLOCKED");
     if (fs9.existsSync(blockedPath)) {
       const reason = fs9.readFileSync(blockedPath, "utf-8").trim();
       return `⛔ BLOCKED by Beekeeper
@@ -22353,6 +23257,7 @@ To unblock: Remove .hive/features/${feature}/BLOCKED`;
     }
     return null;
   };
+  const turnCounters = {};
   const checkDependencies = (feature, taskFolder) => {
     const taskStatus = taskService.getRawStatus(feature, taskFolder);
     if (!taskStatus) {
@@ -22392,6 +23297,9 @@ To unblock: Remove .hive/features/${feature}/BLOCKED`;
   };
   return {
     "experimental.chat.system.transform": async (input, output) => {
+      if (!shouldExecuteHook("experimental.chat.system.transform", configService, turnCounters)) {
+        return;
+      }
       output.system.push(HIVE_SYSTEM_PROMPT);
       const activeFeature = resolveFeature();
       if (activeFeature) {
@@ -22412,6 +23320,9 @@ To unblock: Remove .hive/features/${feature}/BLOCKED`;
         }
       }
     },
+    "experimental.session.compacting": async (_input, output) => {
+      output.context.push(buildCompactionPrompt());
+    },
     "chat.message": async (input, output) => {
       const { agent } = input;
       if (!agent)
@@ -22426,6 +23337,34 @@ To unblock: Remove .hive/features/${feature}/BLOCKED`;
         output.message.variant = configuredVariant;
       }
     },
+    "tool.execute.before": async (input, output) => {
+      if (!shouldExecuteHook("tool.execute.before", configService, turnCounters, { safetyCritical: true })) {
+        return;
+      }
+      if (input.tool !== "bash")
+        return;
+      const sandboxConfig = configService.getSandboxConfig();
+      if (sandboxConfig.mode === "none")
+        return;
+      const command = output.args?.command?.trim();
+      if (!command)
+        return;
+      if (/^HOST:\s*/i.test(command)) {
+        const strippedCommand = command.replace(/^HOST:\s*/i, "");
+        console.warn(`[hive:sandbox] HOST bypass: ${strippedCommand.slice(0, 80)}${strippedCommand.length > 80 ? "..." : ""}`);
+        output.args.command = strippedCommand;
+        return;
+      }
+      const workdir = output.args?.workdir;
+      if (!workdir)
+        return;
+      const hiveWorktreeBase = path8.join(directory, ".hive", ".worktrees");
+      if (!workdir.startsWith(hiveWorktreeBase))
+        return;
+      const wrapped = DockerSandboxService.wrapCommand(workdir, command, sandboxConfig);
+      output.args.command = wrapped;
+      output.args.workdir = undefined;
+    },
     mcp: builtinMcps,
     tool: {
       hive_skill: createHiveSkillTool(filteredSkills),
@@ -22494,8 +23433,8 @@ NEXT: Ask your first clarifying question about this feature.`;
           const feature = resolveFeature(explicitFeature);
           if (!feature)
             return "Error: No feature specified. Create a feature or provide feature param.";
-          const hasDiscovery = content.toLowerCase().includes("## discovery");
-          if (!hasDiscovery) {
+          const discoveryMatch = content.match(/^##\s+Discovery\s*$/im);
+          if (!discoveryMatch) {
             return `BLOCKED: Discovery section required before planning.
 
 Your plan must include a \`## Discovery\` section documenting:
@@ -22504,6 +23443,19 @@ Your plan must include a \`## Discovery\` section documenting:
 - Key decisions made
 
 Add this section to your plan content and try again.`;
+          }
+          const afterDiscovery = content.slice(discoveryMatch.index + discoveryMatch[0].length);
+          const nextHeading = afterDiscovery.search(/^##\s+/m);
+          const discoveryContent = nextHeading > -1 ? afterDiscovery.slice(0, nextHeading).trim() : afterDiscovery.trim();
+          if (discoveryContent.length < 100) {
+            return `BLOCKED: Discovery section is too thin (${discoveryContent.length} chars, minimum 100).
+
+A substantive Discovery section should include:
+- Original request quoted
+- Interview summary (key decisions)
+- Research findings with file:line references
+
+Expand your Discovery section and try again.`;
           }
           captureSession(feature, toolContext);
           const planPath = planService.write(feature, content);
@@ -22724,9 +23676,9 @@ Reminder: start work with hive_worktree_create to use its worktree, and ensure a
             spec: specContent,
             workerPrompt
           });
-          const hiveDir = path7.join(directory, ".hive");
+          const hiveDir = path8.join(directory, ".hive");
           const workerPromptPath = writeWorkerPromptFile(feature, task, workerPrompt, hiveDir);
-          const relativePromptPath = normalizePath(path7.relative(directory, workerPromptPath));
+          const relativePromptPath = normalizePath(path8.relative(directory, workerPromptPath));
           const PREVIEW_MAX_LENGTH = 200;
           const workerPromptPreview = workerPrompt.length > PREVIEW_MAX_LENGTH ? workerPrompt.slice(0, PREVIEW_MAX_LENGTH) + "..." : workerPrompt;
           const taskToolPrompt = `Follow instructions in @${relativePromptPath}`;
@@ -22794,7 +23746,7 @@ Use the \`@path\` attachment syntax in the prompt to reference the file. Do not
         }
       }),
       hive_worktree_commit: tool({
-        description: "Complete task: commit changes to branch, write report. Supports blocked/failed/partial status for worker communication.",
+        description: "Complete task: commit changes to branch, write report. Supports blocked/failed/partial status for worker communication. Returns JSON with ok/terminal semantics for worker control flow.",
         args: {
           task: tool.schema.string().describe("Task folder name"),
           summary: tool.schema.string().describe("Summary of what was done"),
@@ -22808,29 +23760,54 @@ Use the \`@path\` attachment syntax in the prompt to reference the file. Do not
           feature: tool.schema.string().optional().describe("Feature name (defaults to detection or single feature)")
         },
         async execute({ task, summary, status = "completed", blocker, feature: explicitFeature }) {
+          const respond = (payload) => JSON.stringify(payload, null, 2);
           const feature = resolveFeature(explicitFeature);
-          if (!feature)
-            return "Error: No feature specified. Create a feature or provide feature param.";
+          if (!feature) {
+            return respond({
+              ok: false,
+              terminal: false,
+              status: "error",
+              reason: "feature_required",
+              task,
+              taskState: "unknown",
+              message: "No feature specified. Create a feature or provide feature param.",
+              nextAction: "Provide feature explicitly or create/select an active feature, then retry hive_worktree_commit."
+            });
+          }
           const taskInfo = taskService.get(feature, task);
-          if (!taskInfo)
-            return `Error: Task "${task}" not found`;
-          if (taskInfo.status !== "in_progress" && taskInfo.status !== "blocked")
-            return "Error: Task not in progress";
+          if (!taskInfo) {
+            return respond({
+              ok: false,
+              terminal: false,
+              status: "error",
+              reason: "task_not_found",
+              feature,
+              task,
+              taskState: "unknown",
+              message: `Task "${task}" not found`,
+              nextAction: "Check the task folder name in your worker-prompt.md and retry hive_worktree_commit with the correct task id."
+            });
+          }
+          if (taskInfo.status !== "in_progress" && taskInfo.status !== "blocked") {
+            return respond({
+              ok: false,
+              terminal: false,
+              status: "error",
+              reason: "invalid_task_state",
+              feature,
+              task,
+              taskState: taskInfo.status,
+              message: "Task not in progress",
+              nextAction: "Only in_progress or blocked tasks can be committed. Start/resume the task first."
+            });
+          }
+          let verificationNote;
           if (status === "completed") {
-            const verificationKeywords = ["test", "build", "lint", "vitest", "jest", "npm run", "pnpm", "cargo", "pytest", "verified", "passes", "succeeds"];
+            const verificationKeywords = ["test", "build", "lint", "vitest", "jest", "npm run", "pnpm", "cargo", "pytest", "verified", "passes", "succeeds", "ast-grep", "scan"];
             const summaryLower = summary.toLowerCase();
             const hasVerificationMention = verificationKeywords.some((kw) => summaryLower.includes(kw));
             if (!hasVerificationMention) {
-              return `BLOCKED: No verification detected in summary.
-
-Before claiming completion, you must:
-1. Run tests (vitest, jest, pytest, etc.)
-2. Run build (npm run build, cargo build, etc.)
-3. Include verification results in summary
-
-Example summary: "Implemented auth flow. Tests pass (vitest). Build succeeds."
-
-Re-run with updated summary showing verification results.`;
+              verificationNote = "No verification evidence in summary. Orchestrator should run build+test after merge.";
             }
           }
           if (status === "blocked") {
@@ -22840,16 +23817,42 @@ Re-run with updated summary showing verification results.`;
               blocker
             });
             const worktree2 = await worktreeService.get(feature, task);
-            return JSON.stringify({
+            return respond({
+              ok: true,
+              terminal: true,
               status: "blocked",
+              reason: "user_decision_required",
+              feature,
               task,
+              taskState: "blocked",
               summary,
               blocker,
               worktreePath: worktree2?.path,
-              message: 'Task blocked. Hive Master will ask user and resume with hive_worktree_create(continueFrom: "blocked", decision: answer)'
-            }, null, 2);
+              branch: worktree2?.branch,
+              message: 'Task blocked. Hive Master will ask user and resume with hive_worktree_create(continueFrom: "blocked", decision: answer)',
+              nextAction: 'Wait for orchestrator to collect user decision and resume with continueFrom: "blocked".'
+            });
           }
           const commitResult = await worktreeService.commitChanges(feature, task, `hive(${task}): ${summary.slice(0, 50)}`);
+          if (status === "completed" && !commitResult.committed && commitResult.message !== "No changes to commit") {
+            return respond({
+              ok: false,
+              terminal: false,
+              status: "rejected",
+              reason: "commit_failed",
+              feature,
+              task,
+              taskState: taskInfo.status,
+              summary,
+              commit: {
+                committed: commitResult.committed,
+                sha: commitResult.sha,
+                message: commitResult.message
+              },
+              message: `Commit failed: ${commitResult.message || "unknown error"}`,
+              nextAction: "Resolve git/worktree issue, then call hive_worktree_commit again."
+            });
+          }
           const diff = await worktreeService.getDiff(feature, task);
           const statusLabel = status === "completed" ? "success" : status;
           const reportLines = [
@@ -22879,13 +23882,31 @@ Re-run with updated summary showing verification results.`;
           } else {
             reportLines.push("---", "", "## Changes", "", "_No file changes detected_", "");
           }
-          taskService.writeReport(feature, task, reportLines.join(`
+          const reportPath = taskService.writeReport(feature, task, reportLines.join(`
 `));
           const finalStatus = status === "completed" ? "done" : status;
           taskService.update(feature, task, { status: finalStatus, summary });
           const worktree = await worktreeService.get(feature, task);
-          return `Task "${task}" ${status}. Changes committed to branch ${worktree?.branch || "unknown"}.
-Use hive_merge to integrate changes. Worktree preserved at ${worktree?.path || "unknown"}.`;
+          return respond({
+            ok: true,
+            terminal: true,
+            status,
+            feature,
+            task,
+            taskState: finalStatus,
+            summary,
+            ...verificationNote && { verificationNote },
+            commit: {
+              committed: commitResult.committed,
+              sha: commitResult.sha,
+              message: commitResult.message
+            },
+            worktreePath: worktree?.path,
+            branch: worktree?.branch,
+            reportPath,
+            message: `Task "${task}" ${status}.`,
+            nextAction: "Use hive_merge to integrate changes. Worktree is preserved for review."
+          });
         }
       }),
       hive_worktree_discard: tool({
@@ -23066,6 +24087,47 @@ Files changed: ${result.filesChanged?.length || 0}`;
             nextAction: getNextAction(planStatus, tasksSummary, runnable)
           });
         }
+      }),
+      hive_agents_md: tool({
+        description: "Initialize or sync AGENTS.md. init: scan codebase and generate (preview only). sync: propose updates from feature contexts. apply: write approved content to disk.",
+        args: {
+          action: tool.schema.enum(["init", "sync", "apply"]).describe("Action to perform"),
+          feature: tool.schema.string().optional().describe("Feature name for sync action"),
+          content: tool.schema.string().optional().describe("Content to write (required for apply action)")
+        },
+        async execute({ action, feature, content }) {
+          if (action === "init") {
+            const result = await agentsMdService.init();
+            if (result.existed) {
+              return `AGENTS.md already exists (${result.content.length} chars). Use 'sync' to propose updates.`;
+            }
+            return `Generated AGENTS.md from codebase scan (${result.content.length} chars):
+
+${result.content}
+
+⚠️ This has NOT been written to disk. Ask the user via question() whether to write it to AGENTS.md.`;
+          }
+          if (action === "sync") {
+            if (!feature)
+              return "Error: feature name required for sync action";
+            const result = await agentsMdService.sync(feature);
+            if (result.proposals.length === 0) {
+              return "No new findings to sync to AGENTS.md.";
+            }
+            return `Proposed AGENTS.md updates from feature "${feature}":
+
+${result.diff}
+
+⚠️ These changes have NOT been applied. Ask the user via question() whether to apply them.`;
+          }
+          if (action === "apply") {
+            if (!content)
+              return "Error: content required for apply action. Use init or sync first to get content, then apply with the approved content.";
+            const result = agentsMdService.apply(content);
+            return `AGENTS.md ${result.isNew ? "created" : "updated"} (${result.chars} chars) at ${result.path}`;
+          }
+          return "Error: unknown action";
+        }
       })
     },
     command: {
@@ -23080,6 +24142,33 @@ Files changed: ${result.filesChanged?.length || 0}`;
       }
     },
     config: async (opencodeConfig) => {
+      function agentTools(allowed) {
+        const allHiveTools = [
+          "hive_feature_create",
+          "hive_feature_complete",
+          "hive_plan_write",
+          "hive_plan_read",
+          "hive_plan_approve",
+          "hive_tasks_sync",
+          "hive_task_create",
+          "hive_task_update",
+          "hive_worktree_create",
+          "hive_worktree_commit",
+          "hive_worktree_discard",
+          "hive_merge",
+          "hive_context_write",
+          "hive_status",
+          "hive_skill",
+          "hive_agents_md"
+        ];
+        const result = {};
+        for (const tool3 of allHiveTools) {
+          if (!allowed.includes(tool3)) {
+            result[tool3] = false;
+          }
+        }
+        return result;
+      }
       configService.init();
       const hiveUserConfig = configService.getAgentConfig("hive-master");
       const hiveAutoLoadedSkills = await buildAutoLoadedSkillsContent("hive-master", configService, directory);
@@ -23104,6 +24193,7 @@ Files changed: ${result.filesChanged?.length || 0}`;
         temperature: architectUserConfig.temperature ?? 0.7,
         description: "Architect (Planner) - Plans features, interviews, writes plans. NEVER executes.",
         prompt: ARCHITECT_BEE_PROMPT + architectAutoLoadedSkills,
+        tools: agentTools(["hive_feature_create", "hive_plan_write", "hive_plan_read", "hive_context_write", "hive_status", "hive_skill"]),
         permission: {
           edit: "deny",
           task: "allow",
@@ -23122,6 +24212,22 @@ Files changed: ${result.filesChanged?.length || 0}`;
         temperature: swarmUserConfig.temperature ?? 0.5,
         description: "Swarm (Orchestrator) - Orchestrates execution. Delegates, spawns workers, verifies, merges.",
         prompt: SWARM_BEE_PROMPT + swarmAutoLoadedSkills,
+        tools: agentTools([
+          "hive_feature_create",
+          "hive_feature_complete",
+          "hive_plan_read",
+          "hive_plan_approve",
+          "hive_tasks_sync",
+          "hive_task_create",
+          "hive_task_update",
+          "hive_worktree_create",
+          "hive_worktree_discard",
+          "hive_merge",
+          "hive_context_write",
+          "hive_status",
+          "hive_skill",
+          "hive_agents_md"
+        ]),
         permission: {
           question: "allow",
           skill: "allow",
@@ -23138,6 +24244,7 @@ Files changed: ${result.filesChanged?.length || 0}`;
         mode: "subagent",
         description: "Scout (Explorer/Researcher/Retrieval) - Researches codebase + external docs/data.",
         prompt: SCOUT_BEE_PROMPT + scoutAutoLoadedSkills,
+        tools: agentTools(["hive_plan_read", "hive_context_write", "hive_status", "hive_skill"]),
         permission: {
           edit: "deny",
           task: "deny",
@@ -23155,6 +24262,7 @@ Files changed: ${result.filesChanged?.length || 0}`;
         mode: "subagent",
         description: "Forager (Worker/Coder) - Executes tasks directly in isolated worktrees. Never delegates.",
         prompt: FORAGER_BEE_PROMPT + foragerAutoLoadedSkills,
+        tools: agentTools(["hive_plan_read", "hive_worktree_commit", "hive_context_write", "hive_skill"]),
         permission: {
           task: "deny",
           delegate: "deny",
@@ -23170,6 +24278,7 @@ Files changed: ${result.filesChanged?.length || 0}`;
         mode: "subagent",
         description: "Hygienic (Consultant/Reviewer/Debugger) - Reviews plan documentation quality. OKAY/REJECT verdict.",
         prompt: HYGIENIC_BEE_PROMPT + hygienicAutoLoadedSkills,
+        tools: agentTools(["hive_plan_read", "hive_context_write", "hive_status", "hive_skill"]),
         permission: {
           edit: "deny",
           task: "deny",