viepilot 3.8.0 → 3.9.1

package/CHANGELOG.md

@@ -9,6 +9,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [3.9.1] - 2026-05-25
+
+### Fixed
+- BUG-031: `vp-tools hooks install` wrote wrong hook path (`~/.viepilot/hooks/
+  brainstorm-staleness.cjs`) which does not exist; corrected to
+  `{adapter.viepilotDir}/lib/hooks/brainstorm-staleness.cjs`; Stop hook no longer
+  exits non-zero each turn
+- BUG-031: `vp-tools hooks install` (re-run) now detects and removes stale wrong-path
+  entries from settings.json before writing the correct entry
+
+---
+
+## [3.9.0] - 2026-05-24
+
+### Changed
+- ENH-099: skills/vp-auto/SKILL.md — Claude Code adapter tool section expanded with 8 new
+  tools: Monitor, CronCreate/Delete/List, EnterWorktree/ExitWorktree, LSP, PushNotification,
+  EnterPlanMode/ExitPlanMode (sourced from official tools-reference, May 2026)
+- ENH-099: workflows/autonomous.md — TodoWrite deprecated references replaced with
+  TaskCreate/TaskList (disabled since Claude Code v2.1.142); Monitor quality-gate pattern
+  and PushNotification phase-complete notification added
+- ENH-099: docs/dev/agents.md — full 28-event hooks inventory table added; Agent Teams
+  experimental section (TeamCreate, TeamDelete, SendMessage) documented
+
+---
+
 ## [3.8.0] - 2026-05-24
 
 ### Added

package/bin/vp-tools.cjs

@@ -1007,7 +1007,7 @@ ${colors.cyan}Examples:${colors.reset}
             matcher: {},
             hooks: [{
               type: 'command',
-              command: `node ${path.join(home, '.viepilot', 'hooks', 'brainstorm-staleness.cjs')}`
+              command: `node ${path.join(adapter.viepilotDir(home), 'lib', 'hooks', 'brainstorm-staleness.cjs')}`
             }]
           }]
         }
@@ -1024,7 +1024,7 @@ ${colors.cyan}Examples:${colors.reset}
       }
       const home = os.homedir();
       const configPath = adapter.hooks.configFile(home);
-      const hookCommand = `node ${path.join(home, '.viepilot', 'hooks', 'brainstorm-staleness.cjs')}`;
+      const hookCommand = `node ${path.join(adapter.viepilotDir(home), 'lib', 'hooks', 'brainstorm-staleness.cjs')}`;
 
       // Read existing settings.json (create if missing)
       let settings = {};
@@ -1032,15 +1032,22 @@ ${colors.cyan}Examples:${colors.reset}
         try { settings = JSON.parse(fs.readFileSync(configPath, 'utf8')); } catch (_e) { settings = {}; }
       }
 
-      // Merge hook entry — idempotent check
+      // Merge hook entry — migration + idempotent check
       if (!settings.hooks) settings.hooks = {};
       if (!settings.hooks.Stop) settings.hooks.Stop = [];
 
+      // Step A: remove any stale entry with the OLD wrong path
+      const wrongPath = `node ${path.join(home, '.viepilot', 'hooks', 'brainstorm-staleness.cjs')}`;
+      settings.hooks.Stop = settings.hooks.Stop.filter((entry) =>
+        !(Array.isArray(entry.hooks) &&
+          entry.hooks.some((h) => h.type === 'command' && h.command === wrongPath))
+      );
+
+      // Step B: idempotent check for correct path
       const alreadyInstalled = settings.hooks.Stop.some((entry) =>
         Array.isArray(entry.hooks) &&
         entry.hooks.some((h) => h.type === 'command' && h.command === hookCommand)
       );
-
       if (alreadyInstalled) {
         console.log(formatSuccess('ViePilot staleness hook already installed.'));
         console.log(`  Config: ${configPath}`);

package/docs/dev/agents.md

@@ -139,3 +139,85 @@ describes the exact steps — follow them as a scoped sub-prompt.
 - File: `agents/{name}-agent.md` (kebab-case, always ends in `-agent`)
 - Reference: `{name}-agent` (e.g., `tracker-agent`, not `tracker`)
 - Invocation: `Load agents/{name}-agent.md for full spec.`
+
+## Hook Events Reference (ENH-099)
+
+Complete list of 28 hook events supported in Claude Code (as of May 2026).
+Source: [code.claude.com/docs/en/hooks](https://code.claude.com/docs/en/hooks)
+
+| Hook | Fires When | Blocking | Key ViePilot Use |
+|------|-----------|---------|-----------------|
+| `SessionStart` | Session begins/resumes | No | Inject context, set env, watch paths |
+| `SessionEnd` | Session terminates | No | Cleanup, logging |
+| `UserPromptSubmit` | User submits prompt | Yes | Block/augment prompts; set session title |
+| `UserPromptExpansion` | Slash command expands | Yes | Audit `/vp-*` invocations |
+| `PreToolUse` | Before any tool executes | Yes | Block destructive commands, log ops |
+| `PostToolUse` | After tool succeeds | No | Validate output, add context |
+| `PostToolUseFailure` | After tool fails | No | Log failures |
+| `PostToolBatch` | After parallel tools resolve | Yes | Validate parallel fan-out batch results |
+| `PermissionRequest` | Permission dialog appears | Yes | Auto-approve known safe patterns |
+| `PermissionDenied` | Tool call denied | No | Signal retry allowed |
+| `Stop` | Claude finishes responding | Yes | Continue autonomous loop without re-prompt |
+| `StopFailure` | Turn ends due to API error | No | Error logging |
+| `Notification` | Claude Code sends notification | No | Desktop notification / terminal bell |
+| `SubagentStart` | Subagent spawned | No | Log agent start, inject context |
+| `SubagentStop` | Subagent finishes | Yes | Block premature stop, collect output |
+| `TaskCreated` | TaskCreate tool used | Yes | Enforce naming conventions |
+| `TaskCompleted` | Task marked complete | Yes | Trigger quality gate automatically |
+| `TeammateIdle` | Agent team teammate idle | Yes | Keep agent alive / assign next task |
+| `CwdChanged` | Working directory changes | No | Reactive env setup (direnv) |
+| `FileChanged` | Watched file changes | No | React to test/code file saves |
+| `ConfigChange` | Config file changes | Yes | Block unexpected config changes |
+| `WorktreeCreate` | Worktree being created | Yes | Custom worktree setup |
+| `WorktreeRemove` | Worktree being removed | No | Cleanup |
+| `PreCompact` | Before context compaction | Yes | Block compaction during critical phase steps |
+| `PostCompact` | After compaction completes | No | Re-inject phase context |
+| `Setup` | `--init-only` / `-p --init` | No | One-time dependency installation |
+| `InstructionsLoaded` | CLAUDE.md / rules loaded | No | Audit logging |
+| `Elicitation` | MCP server requests user input | Yes | Auto-respond to MCP prompts |
+
+### Exit code behavior
+- **Exit 0**: success; JSON output processed
+- **Exit 2**: blocking error; stderr shown, event blocked
+- **Other non-zero**: non-blocking; first line of stderr shown
+
+### Most impactful hooks for ViePilot autonomous runs
+- `TaskCreated` + `TaskCompleted` → hook-driven quality gates (no manual trigger needed)
+- `PreCompact` + `PostCompact` → protect long phases from mid-run context loss
+- `SubagentStart` + `SubagentStop` → trace agent orchestration
+- `Stop` → enables fully autonomous `/vp-auto` without re-prompting
+- `PostToolBatch` → validate parallel fan-out results (ENH-096/097 pattern)
+
+## Agent Teams (Experimental)
+
+Agent Teams allow multiple Claude Code sessions to communicate via message passing.
+Requires: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` environment variable.
+
+### Tools
+
+| Tool | Description |
+|------|-------------|
+| `TeamCreate` | Create a named team with multiple teammate sessions |
+| `TeamDelete` | Disband team and clean up all teammate processes |
+| `SendMessage` | Send a message to a teammate by name, or resume a stopped subagent |
+
+### Architecture
+
+```
+TeamCreate → defines lead + teammates
+TeamLead   → assigns tasks via SendMessage
+Teammates  → work independently, respond via SendMessage back to lead
+TeamDelete → cleanup after all work complete
+```
+
+### ViePilot roadmap
+
+Agent Teams represent a future upgrade path for the vp-auto orchestration model (ENH-096/097).
+Currently, vp-auto uses fire-and-forget `Agent` spawning (no back-and-forth). Agent Teams
+would enable:
+- Lead orchestrator assigns tasks AND receives status updates
+- Teammates can ask questions mid-task
+- Better handling of inter-task dependency resolution
+
+**Status**: experimental — requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`.
+Not yet used in ViePilot workflows. Tracked via ENH-099.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viepilot",
-  "version": "3.8.0",
+  "version": "3.9.1",
   "description": "**Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**",
   "main": "index.js",
   "bin": {

package/skills/vp-auto/SKILL.md

@@ -67,6 +67,22 @@ Use Claude Code tools: `Bash` (shell), `Read` (file), `Edit` + `Write` (file wri
 `Agent` (spawn subagent — multi-level nesting supported)
 Interactive: `AskUserQuestion` (deferred — preload via ToolSearch before first call)
 
+**Additional tools (ENH-099):**
+- `Monitor` — run command in background, each output line fed back to Claude; use for
+  `npm test --watchAll=false`, dev server tail, CI polling mid-conversation
+- `CronCreate` / `CronDelete` / `CronList` — in-session scheduled prompts (survive
+  `--resume`); use for periodic quality checks during long autonomous phases
+- `EnterWorktree` / `ExitWorktree` — isolated git worktree per task; auto-cleanup on
+  exit if no changes; use for parallel task execution without branch conflicts
+  (not available to subagents)
+- `LSP` — code intelligence: type errors after each edit, jump to definition, find
+  references; requires code intelligence plugin; replaces post-edit `tsc --noEmit`
+- `PushNotification` — desktop + phone push on phase complete or control-point pause
+  (Anthropic infra only; not available on Bedrock/Vertex)
+- `EnterPlanMode` / `ExitPlanMode` — plan gate before implementation: EnterPlanMode
+  switches to read-only planning; ExitPlanMode presents plan for approval before any
+  file edits are made
+
 ## D. Subagent Spawning
 Use `Agent` tool for subagent dispatch. For parallel task execution: fan-out with multiple
 `Agent` calls per cluster (see ADAPTER_CONTEXT.orchestration — claude-code supports parallel: true).

package/workflows/autonomous.md

@@ -259,7 +259,7 @@ ELSE:
 
 **Agent Teams mode** (when `ADAPTER_CONTEXT.orchestration.teams == true` AND pending task count ≥ 8):
 - Set `TEAMS_MODE = true`
-- Activate shared TodoWrite task list for teammate coordination
+- Activate shared TaskCreate/TaskList task list for teammate coordination
 - Each Agent worker reads from the shared list rather than receiving an explicit task prompt
 
 #### 3b-orch: Orchestrator Fan-out (Claude Code only)
@@ -342,7 +342,7 @@ On `QUALITY_GATE: FAIL` or `PARTIAL` → route to control point (retry cluster /
 On `QUALITY_GATE: PASS` → update PHASE-STATE.md (all cluster tasks → done), update TRACKER.md, continue.
 
 **Teams mode** (when `TEAMS_MODE == true`):
-- Write all pending task IDs to shared `TodoWrite` list at phase start
+- Write all pending task IDs to shared task list via `TaskCreate` at phase start
 - Each `Agent(vp-task-executor)` reads next available task from shared list
 - Prevents duplicate execution when dispatching ≥ 8 tasks concurrently
 
@@ -689,6 +689,13 @@ quality_gate:
   - no_lint_errors: true
 ```
 
+**Monitor pattern (ENH-099) — long-running verifications:**
+For tests or builds that take minutes, use the `Monitor` tool instead of blocking `Bash`:
+```
+Monitor: tail -f test-output.log — react when output contains "FAIL" or "Tests: N failed"
+```
+This keeps the agentic loop active while the background process runs.
+
 #### Test Generation — test-generator-agent (ENH-057, BUG-028 fix)
 
 **Trigger**: current task is the last task in the phase AND task.md contains `## Acceptance Criteria`
@@ -845,6 +852,12 @@ Before phase-level verification, run a UI stub check:
 2. Check phase quality gate
 3. Write SUMMARY.md using `templates/phase/SUMMARY.md` as base.
 
+**PushNotification (ENH-099, optional):**
+After phase quality gate passes, send a desktop + phone alert:
+- Message: "Phase {N} — {name} complete ✅ ({tasks} tasks, {tests} tests)"
+- Requires Anthropic-hosted Claude Code (not available on Bedrock/Vertex).
+- Call: `PushNotification` tool with the summary message.
+
    Populate `{{CREATED_FILES}}`, `{{MODIFIED_FILES}}`, `{{DELETED_FILES}}` from git:
    ```bash
    # Get ALL individual files changed since phase start tag