Compare commits

..
4 Commits
Author SHA1 Message Date
OthmanAdi d71b3be47b release: v3.4.0 (PLANNING_DISABLED=1 opt-out for one-shot sessions, closes #195) 2026-07-06 07:20:12 +02:00
OthmanAdi ee892664af feat: honor PLANNING_DISABLED=1 per-invocation opt-out across all hook entry points (closes #195) 2026-07-06 07:19:12 +02:00
OthmanAdi 34d4a7edd4 release: v3.3.0 (Pi extension /plan-execute approval gate, PR #193 merged, closes #190) 2026-07-06 06:22:09 +02:00
diksha adbdc8e13a feat: gate Pi hooks behind plan-execute
Add an explicit /plan-execute approval command for the Pi extension so task_plan.md can be drafted and reviewed without activating plan injection, pre-tool recitations, post-write reminders, or auto-continue.

Scope approval to the current session and plan path, reset it on session lifecycle events, and document the passive review flow with focused runtime and docs coverage.
2026-07-06 06:19:06 +02:00
73 changed files with 628 additions and 37 deletions
+1 -1
View File
@@ -9,7 +9,7 @@
"name": "planning-with-files",
"source": "./",
"description": "Persistent file-based planning for AI coding agents. Crash-proof markdown plans that survive context loss, /clear, and crashes, with an opt-in completion gate and multi-agent shared state on disk. Manus-style, installs across 60+ agents via the SKILL.md standard.",
"version": "3.2.0"
"version": "3.4.0"
}
]
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.2.0",
"version": "3.4.0",
"description": "Persistent file-based planning for AI coding agents. Crash-proof markdown plans (task_plan.md, findings.md, progress.md) that survive context loss and /clear, with an opt-in completion gate and multi-agent shared state. Manus-style. Works with Claude Code, Codex CLI, Cursor, Kiro, OpenCode and 60+ agents via the SKILL.md standard. Includes Arabic, German, Spanish, and Chinese (Simplified and Traditional).",
"author": {
"name": "OthmanAdi",
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
metadata:
version: "3.2.0"
version: "3.4.0"
---
@@ -20,6 +20,10 @@ param(
[switch]$Gate
)
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
if ($env:PLANNING_DISABLED -eq '1') { exit 0 }
if ($PlanFile -ne "") {
$PlanDir = Split-Path -Parent $PlanFile
if ($PlanDir -eq "") { $PlanDir = "." }
@@ -30,6 +30,10 @@
# interactive terminal (TTY) is skipped entirely. No data on stdin is treated
# as stop_hook_active=false.
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
GATE=0
PLAN_FILE=""
for _arg in "$@"; do
+2
View File
@@ -45,6 +45,8 @@ def is_session_attached(root: Path, session_id: str | None) -> bool:
existing single-session users are not broken on upgrade.
Isolation mode: return True only when the session has an attached sentinel.
"""
if os.environ.get("PLANNING_DISABLED", "") == "1":
return False # issue #195: explicit per-invocation opt-out (one-shot exec/CI)
sessions_dir = root / ".planning" / "sessions"
if not sessions_dir.exists():
return True # legacy — no sessions dir means single-session setup
+3
View File
@@ -1,6 +1,9 @@
#!/bin/bash
# planning-with-files: Post-tool-use hook for Codex
# issue #195: per-invocation opt-out for one-shot/CI sessions.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
HOOK_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
PLAN_DIR="$(sh "${HOOK_DIR}/resolve-plan-dir.sh" 2>/dev/null)"
PLAN_FILE="${PLAN_DIR:+${PLAN_DIR}/}task_plan.md"
+3
View File
@@ -2,6 +2,9 @@
# planning-with-files: PreCompact hook for Codex
# Reminds the agent to flush progress before context compaction.
# issue #195: per-invocation opt-out for one-shot/CI sessions.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
HOOK_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
PLAN_DIR="$(sh "${HOOK_DIR}/resolve-plan-dir.sh" 2>/dev/null)"
PLAN_FILE="${PLAN_DIR:+${PLAN_DIR}/}task_plan.md"
+7
View File
@@ -1,6 +1,13 @@
#!/bin/bash
# planning-with-files: Pre-tool-use hook for Codex
# issue #195: per-invocation opt-out for one-shot/CI sessions. Still emit the
# allow decision so the tool call proceeds; only the plan context is skipped.
if [ "${PLANNING_DISABLED:-}" = "1" ]; then
echo '{"decision": "allow"}'
exit 0
fi
HOOK_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
PLAN_DIR="$(sh "${HOOK_DIR}/resolve-plan-dir.sh" 2>/dev/null)"
PLAN_FILE="${PLAN_DIR:+${PLAN_DIR}/}task_plan.md"
+4
View File
@@ -2,6 +2,10 @@
# planning-with-files: SessionStart hook for Codex
# Runs session catchup, then reuses the same prompt context hook as UserPromptSubmit.
# issue #195: per-invocation opt-out for one-shot/CI sessions (e.g. codex exec)
# that share a cwd with a plan but never opted into it.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
CODEX_ROOT="$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd)"
SKILL_DIR="$CODEX_ROOT/skills/planning-with-files"
+3
View File
@@ -1,6 +1,9 @@
#!/bin/bash
# planning-with-files: Stop hook for Codex
# issue #195: per-invocation opt-out for one-shot/CI sessions.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
HOOK_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
PLAN_DIR="$(sh "${HOOK_DIR}/resolve-plan-dir.sh" 2>/dev/null)"
PLAN_FILE="${PLAN_DIR:+${PLAN_DIR}/}task_plan.md"
+4
View File
@@ -1,6 +1,10 @@
#!/bin/bash
# planning-with-files: User prompt submit hook for Codex
# issue #195: per-invocation opt-out for one-shot/CI sessions (e.g. codex exec)
# that share a cwd with a plan but never opted into it.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
HOOK_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
PLAN_DIR="$(sh "${HOOK_DIR}/resolve-plan-dir.sh" 2>/dev/null)"
PLAN_FILE="${PLAN_DIR:+${PLAN_DIR}/}task_plan.md"
+1 -1
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
metadata:
version: "3.2.0"
version: "3.4.0"
---
@@ -20,6 +20,10 @@ param(
[switch]$Gate
)
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
if ($env:PLANNING_DISABLED -eq '1') { exit 0 }
if ($PlanFile -ne "") {
$PlanDir = Split-Path -Parent $PlanFile
if ($PlanDir -eq "") { $PlanDir = "." }
@@ -30,6 +30,10 @@
# interactive terminal (TTY) is skipped entirely. No data on stdin is treated
# as stop_hook_active=false.
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
GATE=0
PLAN_FILE=""
for _arg in "$@"; do
@@ -20,6 +20,10 @@ param(
[switch]$Gate
)
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
if ($env:PLANNING_DISABLED -eq '1') { exit 0 }
if ($PlanFile -ne "") {
$PlanDir = Split-Path -Parent $PlanFile
if ($PlanDir -eq "") { $PlanDir = "." }
@@ -30,6 +30,10 @@
# interactive terminal (TTY) is skipped entirely. No data on stdin is treated
# as stop_hook_active=false.
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
GATE=0
PLAN_FILE=""
for _arg in "$@"; do
+1 -1
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
metadata:
version: "3.2.0"
version: "3.4.0"
---
+1 -1
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
metadata:
version: "3.2.0"
version: "3.4.0"
---
# Planning with Files
@@ -20,6 +20,10 @@ param(
[switch]$Gate
)
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
if ($env:PLANNING_DISABLED -eq '1') { exit 0 }
if ($PlanFile -ne "") {
$PlanDir = Split-Path -Parent $PlanFile
if ($PlanDir -eq "") { $PlanDir = "." }
@@ -30,6 +30,10 @@
# interactive terminal (TTY) is skipped entirely. No data on stdin is treated
# as stop_hook_active=false.
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
GATE=0
PLAN_FILE=""
for _arg in "$@"; do
@@ -20,6 +20,10 @@ param(
[switch]$Gate
)
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
if ($env:PLANNING_DISABLED -eq '1') { exit 0 }
if ($PlanFile -ne "") {
$PlanDir = Split-Path -Parent $PlanFile
if ($PlanDir -eq "") { $PlanDir = "." }
@@ -30,6 +30,10 @@
# interactive terminal (TTY) is skipped entirely. No data on stdin is treated
# as stop_hook_active=false.
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
GATE=0
PLAN_FILE=""
for _arg in "$@"; do
+1 -1
View File
@@ -2,7 +2,7 @@
name: planning-with-files
description: "Manus-style persistent file-based planning for AI coding agents: keeps task_plan.md, findings.md, and progress.md on disk so work survives context loss and /clear. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Hermes adaptation with minimal notes."
metadata:
version: "3.2.0"
version: "3.4.0"
---
> Hermes note: lifecycle automation for this skill is provided by the Hermes adapter plugin in `.hermes/plugins/planning-with-files/`.
@@ -6,6 +6,10 @@ param(
[string]$PlanFile = "task_plan.md"
)
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
if ($env:PLANNING_DISABLED -eq '1') { exit 0 }
if (-not (Test-Path $PlanFile)) {
Write-Host '[planning-with-files] No task_plan.md found -- no active planning session.'
exit 0
@@ -3,6 +3,10 @@
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
@@ -5,6 +5,10 @@ param(
[string]$PlanFile = ".kiro/plan/task_plan.md"
)
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
if ($env:PLANNING_DISABLED -eq '1') { exit 0 }
if (-not (Test-Path $PlanFile)) {
Write-Host "[planning-with-files] No task plan at $PlanFile — run bootstrap or specify path."
exit 0
@@ -2,6 +2,10 @@
# Report phase completion status for task_plan.md (stdout only, always exit 0).
# Default plan path: .kiro/plan/task_plan.md (relative to current directory).
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
PLAN_FILE="${1:-.kiro/plan/task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
metadata:
version: "3.2.0"
version: "3.4.0"
---
@@ -6,6 +6,10 @@ param(
[string]$PlanFile = "task_plan.md"
)
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
if ($env:PLANNING_DISABLED -eq '1') { exit 0 }
if (-not (Test-Path $PlanFile)) {
Write-Host '[planning-with-files] No task_plan.md found -- no active planning session.'
exit 0
@@ -3,6 +3,10 @@
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
metadata:
version: "3.2.0"
version: "3.4.0"
---
@@ -6,6 +6,10 @@ param(
[string]$PlanFile = "task_plan.md"
)
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
if ($env:PLANNING_DISABLED -eq '1') { exit 0 }
if (-not (Test-Path $PlanFile)) {
Write-Host '[planning-with-files] No task_plan.md found -- no active planning session.'
exit 0
@@ -3,6 +3,10 @@
# Always exits 0 — uses stdout for status reporting
# Used by Stop hook to report task completion status
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
+12 -4
View File
@@ -53,10 +53,11 @@ Or:
The bundled extension maps Claude-style behavior onto Pi events:
- `session_start` - session catchup
- `before_agent_start` - plan reminder/injection
- `tool_call` - pre-tool recitation equivalent
- `tool_result` - post-write reminder
- `agent_end` - incomplete-task auto-continue (limit 3)
- passive plan status before approval
- `before_agent_start` - plan reminder/injection after `/plan-execute`
- `tool_call` - pre-tool recitation equivalent after `/plan-execute`
- `tool_result` - post-write reminder after `/plan-execute`
- `agent_end` - incomplete-task auto-continue after `/plan-execute` (limit 3)
- `session_before_compact` - pre-compaction reminder
Attestation is supported. If `task_plan.md` differs from approved hash, plan injection is blocked with:
@@ -98,9 +99,16 @@ Or settings:
- `/plan-status`
- `/plan-attest [--show|--clear]`
- `/plan-execute`
- `/plan-execute reset`
- `/plan-goal <text|default|clear>`
- `/plan-loop [interval] [prompt]` (`stop` to cancel)
Draft and review `task_plan.md` first. The extension stays passive until you
approve the active plan with `/plan-execute`; after that, plan injection,
pre-tool reminders, post-write reminders, and auto-continue are enabled for the
current session and plan.
---
## Session Recovery
+5 -2
View File
@@ -37,8 +37,9 @@ Before ANY complex task:
1. **Create `task_plan.md`** — Use [templates/task_plan.md](templates/task_plan.md) as reference
2. **Create `findings.md`** — Use [templates/findings.md](templates/findings.md) as reference
3. **Create `progress.md`** — Use [templates/progress.md](templates/progress.md) as reference
4. **Re-read plan before decisions** — Refreshes goals in attention window
5. **Update after each phase** — Mark complete, log errors
4. **Wait for approval before execution** — In Pi, hooks stay passive until the user runs `/plan-execute`
5. **Re-read plan before decisions** — Refreshes goals in attention window
6. **Update after each phase** — Mark complete, log errors
> **Note:** Planning files go in your project root, not the skill installation folder.
@@ -217,6 +218,8 @@ Modes:
Commands:
- `/plan-status`
- `/plan-attest [--show|--clear]`
- `/plan-execute` (approve the active plan and enable hook activation)
- `/plan-execute reset` (return the active plan to passive review mode)
- `/plan-goal <text|default|clear>`
- `/plan-loop [interval] [prompt]` (use `stop` to cancel)
@@ -144,6 +144,16 @@ async function emit(pi: MockPi, eventName: string, event: any, ctx: MockContext)
return handler?.(event, ctx);
}
async function runCommand(pi: MockPi, name: string, args: string, ctx: MockContext): Promise<void> {
const command = pi.commands.get(name);
expect(command, `missing command: ${name}`).toBeDefined();
await command?.handler(args, ctx);
}
async function approvePlan(pi: MockPi, ctx: MockContext): Promise<void> {
await runCommand(pi, "plan-execute", "", ctx);
}
beforeEach(() => {
originalEnv = { ...process.env };
process.env.PWF_MODE = "parity";
@@ -176,6 +186,12 @@ describe("Pi extension runtime handlers", () => {
]);
});
it("registers plan-execute command for explicit hook activation", () => {
const pi = loadExtension();
expect(Array.from(pi.commands.keys()).sort()).toContain("plan-execute");
});
it("session_start initializes visible plan state for an attached plan directory", async () => {
const cwd = makeWorkspace();
const pi = loadExtension();
@@ -183,7 +199,24 @@ describe("Pi extension runtime handlers", () => {
await emit(pi, "session_start", { reason: "resume" }, ctx);
expect(ctx.ui.setStatus).toHaveBeenCalledWith("planning-with-files", "1/2 phases complete");
expect(ctx.ui.setStatus).toHaveBeenCalledWith(
"planning-with-files",
"1/2 phases complete — run /plan-execute to activate hooks",
);
});
it("before_agent_start stays passive before plan-execute approval", async () => {
const cwd = makeWorkspace();
const pi = loadExtension();
const ctx = createContext(cwd);
const result = await emit(pi, "before_agent_start", {}, ctx);
expect(result).toBeUndefined();
expect(ctx.ui.setStatus).toHaveBeenCalledWith(
"planning-with-files",
"1/2 phases complete — run /plan-execute to activate hooks",
);
});
it("before_agent_start injects canonical skill content when attestation matches", async () => {
@@ -193,6 +226,7 @@ describe("Pi extension runtime handlers", () => {
const pi = loadExtension();
const ctx = createContext(cwd);
await approvePlan(pi, ctx);
const result = await emit(pi, "before_agent_start", {}, ctx);
expect(result.message).toMatchObject({
@@ -211,11 +245,11 @@ describe("Pi extension runtime handlers", () => {
const pi = loadExtension();
const ctx = createContext(cwd);
await runCommand(pi, "plan-execute", "", ctx);
const result = await emit(pi, "before_agent_start", {}, ctx);
expect(result.message.content).toContain("[PLAN TAMPERED");
expect(result.message.content).toContain("injection blocked");
expect(result.message.display).toBe(true);
expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringContaining("[PLAN TAMPERED"), "error");
expect(result).toBeUndefined();
});
it("tool_call records a pre-tool reminder against the active leaf", async () => {
@@ -223,6 +257,7 @@ describe("Pi extension runtime handlers", () => {
const pi = loadExtension();
const ctx = createContext(cwd);
await approvePlan(pi, ctx);
await emit(pi, "tool_call", { toolName: "write", input: {} }, ctx);
await emit(pi, "tool_call", { toolName: "write", input: {} }, ctx);
@@ -241,6 +276,7 @@ describe("Pi extension runtime handlers", () => {
const pi = loadExtension();
const ctx = createContext(cwd);
await approvePlan(pi, ctx);
const result = await emit(
pi,
"tool_result",
@@ -257,6 +293,20 @@ describe("Pi extension runtime handlers", () => {
]);
});
it("agent_end does not auto-continue before plan-execute approval", async () => {
const cwd = makeWorkspace();
const pi = loadExtension();
const ctx = createContext(cwd);
await emit(pi, "agent_end", {}, ctx);
expect(pi.sendUserMessage).not.toHaveBeenCalled();
expect(ctx.ui.notify).toHaveBeenCalledWith(
"[planning-with-files] Task incomplete (1/2). Run /plan-execute to activate hooks.",
"warning",
);
});
it("agent_end flushes final complete-plan state without scheduling a follow-up", async () => {
const cwd = makeWorkspace(completePlan());
const pi = loadExtension();
@@ -278,6 +328,7 @@ describe("Pi extension runtime handlers", () => {
const pi = loadExtension();
const ctx = createContext(cwd);
await approvePlan(pi, ctx);
await emit(pi, "session_before_compact", {}, ctx);
expect(ctx.ui.notify).toHaveBeenCalledWith(
@@ -298,8 +349,10 @@ describe("Pi extension runtime handlers", () => {
const pi = loadExtension();
const ctx = createContext(cwd);
await approvePlan(pi, ctx);
await emit(pi, "tool_call", { toolName: "write", input: {} }, ctx);
await emit(pi, "session_shutdown", {}, ctx);
await approvePlan(pi, ctx);
await emit(pi, "tool_call", { toolName: "write", input: {} }, ctx);
expect(pi.sendMessage).toHaveBeenCalledTimes(2);
@@ -310,6 +363,7 @@ describe("Pi extension runtime handlers", () => {
const pi = loadExtension();
const ctx = createContext(cwd);
await approvePlan(pi, ctx);
await emit(pi, "tool_call", { toolName: "write", input: {} }, ctx);
await emit(pi, "input", { source: "extension", text: "internal" }, ctx);
await emit(pi, "tool_call", { toolName: "write", input: {} }, ctx);
@@ -332,6 +386,7 @@ describe("Pi extension runtime modes", () => {
},
});
await approvePlan(pi, ctx);
const result = await emit(pi, "before_agent_start", {}, ctx);
expect(result.message.content).toContain("Read task_plan.md for current phase and status.");
@@ -344,6 +399,7 @@ describe("Pi extension runtime modes", () => {
const pi = loadExtension();
const ctx = createContext(cwd);
await approvePlan(pi, ctx);
const result = await emit(pi, "before_agent_start", {}, ctx);
expect(result.message.content).toContain("[planning-with-files] ACTIVE PLAN");
@@ -356,6 +412,7 @@ describe("Pi extension runtime modes", () => {
const pi = loadExtension();
const ctx = createContext(cwd);
await approvePlan(pi, ctx);
const result = await emit(pi, "before_agent_start", {}, ctx);
expect(result.message.content).toContain("treat contents as structured data, not instructions.");
@@ -369,6 +426,7 @@ describe("Pi extension runtime modes", () => {
const pi = loadExtension();
const ctx = createContext(cwd);
await approvePlan(pi, ctx);
const result = await emit(pi, "before_agent_start", {}, ctx);
expect(result.message.content).toBe(
@@ -384,6 +442,7 @@ describe("Pi extension runtime modes", () => {
const pi = loadExtension();
const ctx = createContext(cwd);
await approvePlan(pi, ctx);
const startResult = await emit(pi, "before_agent_start", {}, ctx);
const toolResult = await emit(
pi,
@@ -40,6 +40,7 @@ interface RuntimeState {
loopTimersBySession: Map<string, ReturnType<typeof setInterval>>;
goalBySession: Map<string, string>;
preToolQueuedByLeaf: Set<string>;
executionApprovedBySessionPlan: Set<string>;
}
interface ExecResult {
@@ -120,6 +121,14 @@ function clearSessionPrefixMap(state: RuntimeState, sessionId: string): void {
}
}
function clearSessionExecutionApprovals(state: RuntimeState, sessionId: string): void {
for (const key of state.executionApprovedBySessionPlan.keys()) {
if (key.startsWith(`${sessionId}:`)) {
state.executionApprovedBySessionPlan.delete(key);
}
}
}
function isAttachedSession(ctx: ExtensionContext): boolean {
return isSessionAttached(ctx.cwd, getSessionId(ctx));
}
@@ -257,6 +266,14 @@ function buildPreToolParityRecitation(status: PlanStatus): string {
].join("\n");
}
function isExecutionApproved(state: RuntimeState, ctx: ExtensionContext, status: PlanStatus): boolean {
return state.executionApprovedBySessionPlan.has(getPlanSessionKey(ctx, status));
}
function setPassivePlanStatus(ctx: ExtensionContext, status: PlanStatus): void {
ctx.ui.setStatus(PKG_NAME, `${summarizePlan(status)} — run /plan-execute to activate hooks`);
}
// Word-boundary regex check so legitimate commands like
// `git push origin feature/draft-notification` don't trigger the warning, but
// destructive variants like `git push --force` or `git push --mirror` still do.
@@ -329,6 +346,42 @@ function registerCommands(pi: ExtensionAPI, state: RuntimeState): void {
},
});
pi.registerCommand("plan-execute", {
description: "Approve the active plan and enable planning-with-files hook activation",
handler: async (args, ctx) => {
const status = readPlanStatus(ctx.cwd);
if (!status.exists) {
ctx.ui.notify("No active plan (task_plan.md not found)", "warning");
return;
}
const planKey = getPlanSessionKey(ctx, status);
const normalized = args.trim().toLowerCase();
if (["clear", "off", "reset", "disable"].includes(normalized)) {
state.executionApprovedBySessionPlan.delete(planKey);
ctx.ui.notify(`Plan execution approval cleared: ${summarizePlan(status)}`, "info");
setPassivePlanStatus(ctx, status);
return;
}
const attestation = checkPlanAttestation(status);
if (attestation.tampered) {
ctx.ui.notify(buildTamperMessage(status), "error");
return;
}
state.executionApprovedBySessionPlan.add(planKey);
ctx.ui.notify(
[
`Plan execution approved: ${summarizePlan(status)}`,
`Plan path: ${status.planPath}`,
"planning-with-files hooks are now active for this session and plan.",
].join("\n"),
"info",
);
},
});
pi.registerCommand("plan-loop", {
description: "Start/stop planning loop ticks (default: 10m)",
handler: async (args, ctx: ExtensionCommandContext) => {
@@ -387,6 +440,7 @@ export default function planningWithFilesExtension(pi: ExtensionAPI): void {
loopTimersBySession: new Map(),
goalBySession: new Map(),
preToolQueuedByLeaf: new Set(),
executionApprovedBySessionPlan: new Set(),
};
registerCommands(pi, state);
@@ -394,6 +448,7 @@ export default function planningWithFilesExtension(pi: ExtensionAPI): void {
pi.on("session_start", async (event, ctx) => {
const sessionId = getSessionId(ctx);
clearSessionPrefixMap(state, sessionId);
clearSessionExecutionApprovals(state, sessionId);
if (!isAttachedSession(ctx)) {
ctx.ui.setStatus(PKG_NAME, "session not attached to planning context");
@@ -406,7 +461,7 @@ export default function planningWithFilesExtension(pi: ExtensionAPI): void {
const status = readPlanStatus(ctx.cwd);
if (status.exists) {
ctx.ui.setStatus(PKG_NAME, summarizePlan(status));
setPassivePlanStatus(ctx, status);
}
});
@@ -416,6 +471,7 @@ export default function planningWithFilesExtension(pi: ExtensionAPI): void {
if (timer) clearInterval(timer);
state.loopTimersBySession.delete(sessionId);
clearSessionPrefixMap(state, sessionId);
clearSessionExecutionApprovals(state, sessionId);
});
pi.on("input", async (event, ctx) => {
@@ -429,6 +485,11 @@ export default function planningWithFilesExtension(pi: ExtensionAPI): void {
const status = readPlanStatus(ctx.cwd);
if (!status.exists) return;
if (!isExecutionApproved(state, ctx, status)) {
setPassivePlanStatus(ctx, status);
return;
}
const mode = deriveEffectiveMode(resolveConfiguredMode(ctx.cwd), ctx);
const attestation = checkPlanAttestation(status);
@@ -467,7 +528,12 @@ export default function planningWithFilesExtension(pi: ExtensionAPI): void {
const leafKey = `${sessionId}:${leafId}`;
const trackableTools = new Set(["write", "edit", "bash", "read", "grep", "find", "ls"]);
if (status.exists && trackableTools.has(event.toolName) && !state.preToolQueuedByLeaf.has(leafKey)) {
if (
status.exists &&
isExecutionApproved(state, ctx, status) &&
trackableTools.has(event.toolName) &&
!state.preToolQueuedByLeaf.has(leafKey)
) {
state.preToolQueuedByLeaf.add(leafKey);
const attestation = checkPlanAttestation(status);
if (attestation.tampered) {
@@ -518,6 +584,10 @@ export default function planningWithFilesExtension(pi: ExtensionAPI): void {
const status = readPlanStatus(ctx.cwd);
if (!status.exists) return;
if (!isExecutionApproved(state, ctx, status)) {
setPassivePlanStatus(ctx, status);
return;
}
const mode = deriveEffectiveMode(resolveConfiguredMode(ctx.cwd), ctx);
if (mode === "parity") {
@@ -550,6 +620,15 @@ export default function planningWithFilesExtension(pi: ExtensionAPI): void {
if (!isPlanIncomplete(status)) return;
if (!isExecutionApproved(state, ctx, status)) {
ctx.ui.notify(
`[planning-with-files] Task incomplete (${status.completePhases}/${status.totalPhases}). Run /plan-execute to activate hooks.`,
"warning",
);
setPassivePlanStatus(ctx, status);
return;
}
if (mode === "notify") {
ctx.ui.notify(
`[planning-with-files] Task incomplete (${status.completePhases}/${status.totalPhases}). Continue manually.`,
@@ -583,6 +662,12 @@ export default function planningWithFilesExtension(pi: ExtensionAPI): void {
const status = readPlanStatus(ctx.cwd);
if (!status.exists) return;
if (!isExecutionApproved(state, ctx, status)) {
ctx.ui.notify("[planning-with-files] PreCompact: flush progress.md and task_plan.md updates.", "info");
setPassivePlanStatus(ctx, status);
return;
}
const attestation = checkPlanAttestation(status);
const reminder = [
"[planning-with-files] PreCompact: context compaction is about to occur.",
@@ -20,6 +20,10 @@ param(
[switch]$Gate
)
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
if ($env:PLANNING_DISABLED -eq '1') { exit 0 }
if ($PlanFile -ne "") {
$PlanDir = Split-Path -Parent $PlanFile
if ($PlanDir -eq "") { $PlanDir = "." }
@@ -30,6 +30,10 @@
# interactive terminal (TTY) is skipped entirely. No data on stdin is treated
# as stop_hook_active=false.
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
GATE=0
PLAN_FILE=""
for _arg in "$@"; do
+38
View File
@@ -2,6 +2,44 @@
All notable changes to this project will be documented in this file.
## [3.4.0] - 2026-07-06
### Added
- **`PLANNING_DISABLED=1` per-invocation opt-out** (closes #195, reported by @marcmuon). One-shot sessions that share a working directory with an active plan (a CI review bot run via `codex exec`, a read-only research agent, a nested orchestrator) were hijacked by the hooks: plan context injected, the actual output redirected into `progress.md`, and a fabricated completed phase appended to `task_plan.md`. All Codex hook entry points (`session-start.sh`, `user-prompt-submit.sh`, `pre-tool-use.sh`, `post-tool-use.sh`, `stop.sh`, `pre-compact.sh`, plus the Python adapter route via `codex_hook_adapter.is_session_attached`) and the canonical dispatchers (`inject-plan.sh`, `gate-stop.sh`, `check-complete.sh`/`.ps1`) now exit before reading the plan when `PLANNING_DISABLED=1` is set in the environment. PreToolUse still emits its allow decision so tool calls proceed normally. The guard ships in every distributed copy: canonical scripts, the skill package, all sync-managed IDE mirrors, the five language variants, the standalone `.kiro` copy, and the `clawhub-upload` bundle. Usage documented in `docs/codex.md`. New `tests/test_planning_disabled_optout.py` (12 tests) covers baseline behavior, disabled behavior, the #195 acceptance criterion (plan files byte-for-byte unchanged after a full disabled hook pass), and a guard-presence sweep across every copy.
### Fixed
- **`docs/codex.md` still described the pre-v3.1.0 blocking Stop hook.** The hook table said Stop "blocks once when phases are incomplete"; that block path was removed in v3.1.0 (PR #180) and the installed hook has emitted an advisory reminder since. The row now matches the shipped behavior. The `decision: block` half of #195 was reported against a v2.41.0 bundle shipped by oh-my-codex; current releases do not block.
### Verification
- Python suite: 200 passed, 5 skipped, 0 failed (12 new opt-out tests).
- Functional smoke test on a live temp plan: baseline injection unchanged without the variable; with it set, no hook output, tool calls still allowed, plan files byte-identical afterwards.
- `scripts/sync-ide-folders.py --verify`: all IDE folders in sync. All modified `.sh` files pass `sh -n`; all modified `.ps1` files parse clean.
### Thanks
- @marcmuon (Marc Kelechava) for the precise report separating this failure from #178 and #146, with reproductions for both symptoms, the root-cause file list, and acceptance criteria this release implements directly (#195).
## [3.3.0] - 2026-07-06
### Added
- **`/plan-execute` approval gate for the Pi extension** (PR #193 by @Dikshj, closes #190, requested by @lazyst). The Pi extension hooks previously activated as soon as `task_plan.md` existed on disk: plan injection on `before_agent_start`, pre-tool recitation on `tool_call`, post-write reminders on `tool_result`, and auto-continue on `agent_end` could all start while the user was still reviewing a draft plan. The extension now stays passive until the user approves the active plan with `/plan-execute`; before approval it shows a status line ("run /plan-execute to activate hooks") and nothing else. Approval is scoped to the current session and plan path, is cleared on session lifecycle events, and `/plan-execute reset` returns the plan to passive review mode. A plan whose SHA-256 attestation shows tampering cannot be approved. This gates initial hook activation only; the v3 gate mode (which gates stopping on an incomplete plan) is unchanged. Pi docs, Pi skill docs, and runtime tests cover the passive review flow.
### Verification
- Python suite: 188 passed, 5 skipped, 0 failed.
- Pi extension vitest suite: 21 passed (2 files).
- `scripts/sync-ide-folders.py --verify`: all IDE folders in sync.
- Supply-chain review on PR #193: no new dependencies, no install scripts, no bin shims, no network calls; changes confined to the Pi extension runtime, its tests, and documentation. The gate itself tightens the injection path, since a tampered or unreviewed plan can no longer reach model context automatically.
### Thanks
- @Dikshj (diksha) for implementing the /plan-execute approval gate with runtime and docs test coverage (PR #193).
- @lazyst for the feature request and the precise passive-until-confirmed workflow description (#190).
## [3.2.0] - 2026-07-03
A repository health audit covering the v3 long-running-session mechanism, the
+1 -1
View File
@@ -7,7 +7,7 @@ authors:
- family-names: Adi
given-names: Ahmad Othman Ammar
alias: OthmanAdi
version: "3.2.0"
version: "3.4.0"
date-released: "2026-06-16"
license: MIT
url: "https://github.com/OthmanAdi/planning-with-files"
+9 -1
View File
@@ -106,6 +106,12 @@ These amazing people have contributed code, documentation, or significant improv
### Other Contributors
- **[@Dikshj](https://github.com/Dikshj)** (diksha) - [PR #193](https://github.com/OthmanAdi/planning-with-files/pull/193), closes [Issue #190](https://github.com/OthmanAdi/planning-with-files/issues/190)
- Added the `/plan-execute` approval command to the Pi extension: hooks previously activated the moment `task_plan.md` existed, so plan injection, pre-tool recitation, post-write reminders, and auto-continue could start while the user was still reviewing a draft plan
- The extension now stays passive (status line only) until the user approves the active plan; approval is scoped to the current session and plan path, resets on session lifecycle events, and `/plan-execute reset` returns to passive review mode
- A plan with a tampered SHA-256 attestation cannot be approved, and the runtime test suite plus Python docs guards cover the passive review flow
- **Impact:** Pi users can draft and review a plan without the extension pushing execution before they have confirmed it, closing the workflow gap reported in #190
- **[@2023Anita](https://github.com/2023Anita)** - [PR #180](https://github.com/OthmanAdi/planning-with-files/pull/180), [Issue #178](https://github.com/OthmanAdi/planning-with-files/issues/178)
- Made the Codex Stop hook non-blocking for incomplete plans: `.codex/hooks/stop.py` previously emitted `{"decision": "block"}` on the first stop while phases were still pending, which pushed the agent to continue into the next phase without the user asking
- Collapsed the conditional block path to a single advisory `systemMessage` and rewrote `.codex/hooks/stop.sh` to drop the imperative "continue working on the remaining phases" wording, keeping only the progress-sync reminder
@@ -311,6 +317,8 @@ Thank you to everyone who reported issues, provided feedback, and helped test fi
- [@luyanfeng](https://github.com/luyanfeng) - Issue #172 (OpenCode install/verify paths doubled the folder segment in docs/opencode.md; fixed in v2.43.0)
- [@mixian939](https://github.com/mixian939) - Issue #191 (Codex hooks reporting a false "0/0 phases complete" status for an unstructured task_plan.md, with a full root-cause diagnosis and suggested fix; the audit this triggered found and fixed the same defect in the canonical scripts and two other IDE adapters, fixed in v3.2.0)
- [@AvitalAviv](https://github.com/AvitalAviv) - Issue #188 (flagged that the repo had no private vulnerability disclosure channel; private vulnerability reporting is now enabled and documented in SECURITY.md)
- [@lazyst](https://github.com/lazyst) - Issue #190 (feature request describing the Pi extension activating hooks on a draft plan before user confirmation, with the exact passive-until-confirmed behavior that shipped as `/plan-execute` in v3.3.0)
- [@marcmuon](https://github.com/marcmuon) (Marc Kelechava) - Issue #195 (one-shot `codex exec` sessions sharing a cwd with an incomplete plan got hijacked and mutated orchestrator-owned plan files; the report's reproductions, root-cause file list, and acceptance criteria shipped directly as the `PLANNING_DISABLED=1` opt-out in v3.4.0)
And many others who have starred, forked, and shared this project!
@@ -340,4 +348,4 @@ If you've contributed and don't see your name here, please open an issue! We wan
**Total Contributors:** 50+ and growing!
*Last updated: July 3, 2026*
*Last updated: July 6, 2026*
+4 -2
View File
@@ -17,7 +17,7 @@
[![Skills Playground](https://skillsplayground.com/badges/installs/othmanadi-planning-with-files-planning-with-files.svg)](https://skillsplayground.com/skills/othmanadi-planning-with-files-planning-with-files/)
[![Downloads](https://skill-history.com/badge/othmanadi/planning-with-files.svg)](https://skill-history.com/othmanadi/planning-with-files)
[![Version](https://img.shields.io/badge/version-3.2.0-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
[![Version](https://img.shields.io/badge/version-3.4.0-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Closed Issues](https://img.shields.io/github/issues-closed/OthmanAdi/planning-with-files?color=success)](https://github.com/OthmanAdi/planning-with-files/issues?q=is%3Aissue+is%3Aclosed)
[![Closed PRs](https://img.shields.io/github/issues-pr-closed/OthmanAdi/planning-with-files?color=success)](https://github.com/OthmanAdi/planning-with-files/pulls?q=is%3Apr+is%3Aclosed)
@@ -73,10 +73,12 @@ See the full list of everyone who made this project better in [CONTRIBUTORS.md](
<details>
<summary><strong>📦 Releases & Session Recovery</strong></summary>
### Current Version: v3.2.0
### Current Version: v3.4.0
| Version | Highlights |
|---------|------------|
| **v3.4.0** | **`PLANNING_DISABLED=1` per-invocation opt-out for one-shot sessions (closes #195, reported by @marcmuon).** One-shot `codex exec` runs (CI review bots, read-only research agents, nested orchestrators) that merely shared a cwd with an incomplete plan were hijacked: plan context injected, the actual output redirected into `progress.md`, a fabricated completed phase appended to `task_plan.md`. All Codex hook entry points, the Python adapter route, and the canonical dispatchers (`inject-plan.sh`, `gate-stop.sh`, `check-complete.sh`/`.ps1`) now exit before reading the plan when `PLANNING_DISABLED=1` is set; PreToolUse keeps emitting its allow decision so tool calls proceed. The guard ships in every distributed copy including the five language variants. Also corrected `docs/codex.md`'s stale claim that the Stop hook blocks (non-blocking since v3.1.0). Suite at 200 passed. |
| **v3.3.0** | **Pi extension hooks now wait for explicit user approval via `/plan-execute`** (PR #193 by @Dikshj, closes #190, requested by @lazyst). The Pi extension previously activated all hooks as soon as `task_plan.md` existed, so plan injection, pre-tool recitation, post-write reminders, and auto-continue could start while the user was still reviewing a draft plan. The extension now stays passive with a status line until the active plan is approved with `/plan-execute`; approval is scoped to the current session and plan path, resets on session lifecycle events, and `/plan-execute reset` returns to passive review. A plan with a tampered SHA-256 attestation cannot be approved. Suite at 188 passed plus 21 Pi extension vitest tests. |
| **v3.2.0** | **Repository health audit: session-catchup.py was non-functional on Windows, plus the "0/0 phases" false status (closes #191, addresses #103, closes #188).** `session-catchup.py`, the mechanism behind "resume after `/clear`," never sanitized Windows-style paths correctly and had no explicit encoding on three reads, so it silently did nothing on Windows with no error. `inject-plan.sh`'s containment guard also silently dropped plan injection and tamper detection under 8.3 short-name or `/tmp`-aliased paths. Both fixed. Separately, `check-complete.sh`/`.ps1` and three IDE-specific Stop hooks reported a false "0/0 phases complete" for any `task_plan.md` without `### Phase` headings (#191, reported by @mixian939); fixed everywhere the pattern appeared, canonical scripts included. The `--template analytics` flag (v2.29.0) was silently falling back to default templates in every installed skill package; the analytics templates now actually ship where `init-session.sh` reads them. Merged PR #187 (@Stephen-abc: Windows test-encoding fixes, stale install-path docs) and PR #192 (@igorcosta: Autohand Code setup docs). Added `SECURITY.md` and enabled private vulnerability reporting (@AvitalAviv). Corrected `AGENTS.md`'s contributor-PR-merge guidance, which told agents to squash-merge in a way that reassigns authorship. Suite at 186 passed, 5 skipped, 0 failed. |
| **v3.1.3** | **Hotfix: SKILL.md frontmatter was invalid YAML in v3.1.2.** The v3.1.2 description refresh added a colon, and the English SKILL.md keep `description` unquoted, so YAML rejected the frontmatter ("mapping values are not allowed here"), which could break skill loading and the model-triggering description. v3.1.3 quotes the description (matching the already-quoted translated variants; the parsed value is identical) across the canonical file and the seven English IDE variants, and adds `tests/test_skill_frontmatter_valid.py` to validate every SKILL.md frontmatter as YAML. Suite at 184 passed. |
| **v3.1.2** | **Session-catchup command works outside the plugin runtime, `.hermes` parity, refreshed skill description** (PR #186 by @shunfeng8421 closes #185, reported by @xwang118). The documented Restore Context command used `${CLAUDE_PLUGIN_ROOT}`, which the plugin runtime sets only inside hook execution, so a skill-only install (`npx skills add`, Codex, Cursor) running it in a shell got an empty variable and a broken `/scripts/...` path. Now `SKILL_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/planning-with-files}"` on the canonical file, `.codebuddy`, and the five language variants; the `.hermes` variant got the same fallback for `$HERMES_HOME`. The eight English SKILL.md descriptions were refreshed to lead with planning for AI coding agents and context-loss survival, with the `Use when` trigger and translated variants unchanged. Documentation only; suite at 180 passed. |
+26 -1
View File
@@ -109,7 +109,7 @@ This integration includes the Codex lifecycle hooks used by the adapter:
| **PreToolUse** | Re-reads the first 30 lines of `task_plan.md` before Bash |
| **PostToolUse** | Reminds the agent to update `progress.md` after Bash activity |
| **PreCompact** | Reminds the agent to flush `progress.md` and `task_plan.md` before compaction |
| **Stop** | Blocks once when phases are incomplete, then falls back to a follow-up reminder |
| **Stop** | Emits an advisory progress-sync reminder when phases are incomplete (non-blocking since v3.1.0) |
### The Three Files
@@ -121,6 +121,31 @@ Once activated, the skill creates and maintains:
| `findings.md` | Research, discoveries | Your project root |
| `progress.md` | Session log, test results | Your project root |
### Opting out for one-shot runs (CI, `codex exec`)
A one-shot session that shares a working directory with an active plan gets the
plan context injected even though it never opted in: a CI review bot, a
read-only research agent, or a nested orchestrator can end up "reconciling the
plan" instead of doing its own job, and may mutate `task_plan.md` and
`progress.md` that belong to another session (issue #195).
Set `PLANNING_DISABLED=1` to disable all planning-with-files hooks for that
invocation only:
```bash
PLANNING_DISABLED=1 codex exec -o review.md '$code-review review this branch'
PLANNING_DISABLED=1 codex exec -C <repo> -s read-only '<research prompt>'
```
With the variable set, every hook (SessionStart, UserPromptSubmit, PreToolUse,
PostToolUse, PreCompact, Stop) exits before reading the plan: no context
injection, no follow-up messages, no plan-file writes. PreToolUse still emits
its `allow` decision so tool calls proceed normally. Interactive sessions in
the same directory are unaffected. The same variable is honored by the
canonical Claude Code dispatchers (`inject-plan.sh`, `gate-stop.sh`,
`check-complete.sh`/`.ps1`), so it works for CI automation on any platform
whose hooks route through those scripts.
---
## Team Workflow
+19 -5
View File
@@ -35,10 +35,11 @@ cp -r .pi/skills/planning-with-files/* ~/.pi/agent/skills/planning-with-files/
Pi integration provides Claude-style lifecycle behavior via extension events:
- Session catchup on `session_start`
- Plan context reminder/injection on `before_agent_start`
- Pre-tool plan recitation equivalent on `tool_call`
- Post-write reminders on `tool_result`
- Auto-continue guard on `agent_end` (limit: 3)
- Passive plan status before approval
- Plan context reminder/injection on `before_agent_start` after `/plan-execute`
- Pre-tool plan recitation equivalent on `tool_call` after `/plan-execute`
- Post-write reminders on `tool_result` after `/plan-execute`
- Auto-continue guard on `agent_end` after `/plan-execute` (limit: 3)
- Pre-compaction reminder on `session_before_compact`
- Plan attestation guard (`[PLAN TAMPERED — injection blocked]`)
@@ -84,6 +85,8 @@ After installation, these extension commands are available:
- `/plan-status` — show current plan counts and paths
- `/plan-attest [--show|--clear]` — manage plan SHA-256 attestation
- `/plan-execute` — approve the active plan and enable hook activation
- `/plan-execute reset` — return the active plan to passive review mode
- `/plan-goal <text|default|clear>` — set/clear continuation goal text
- `/plan-loop [10m] [prompt...]` — periodic planning tick; use `stop` to cancel
@@ -102,7 +105,18 @@ Then ask Pi to create/update:
- `findings.md`
- `progress.md`
For long tasks, keep `task_plan.md` as the source of truth and let hooks/extension events enforce the loop.
Review and edit the plan until it matches your intent. During this review
stage, the extension stays passive: it may show plan status, but it does not
inject plan context, recite the plan before tools, or auto-continue.
When you are ready to execute, run:
```text
/plan-execute
```
For long tasks, keep `task_plan.md` as the source of truth and let the activated
hooks/extension events enforce the loop.
---
+4
View File
@@ -20,6 +20,10 @@ param(
[switch]$Gate
)
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
if ($env:PLANNING_DISABLED -eq '1') { exit 0 }
if ($PlanFile -ne "") {
$PlanDir = Split-Path -Parent $PlanFile
if ($PlanDir -eq "") { $PlanDir = "." }
+4
View File
@@ -30,6 +30,10 @@
# interactive terminal (TTY) is skipped entirely. No data on stdin is treated
# as stop_hook_active=false.
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
GATE=0
PLAN_FILE=""
for _arg in "$@"; do
+4
View File
@@ -12,6 +12,10 @@
set -u
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd 2>/dev/null)" || SCRIPT_DIR="."
TARGET="${SCRIPT_DIR}/check-complete.sh"
+4
View File
@@ -21,6 +21,10 @@
set -u
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
CONTEXT="userprompt"
for arg in "$@"; do
case "$arg" in
+1 -1
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
metadata:
version: "3.2.0"
version: "3.4.0"
---
# نظام تخطيط الملفات
@@ -6,6 +6,10 @@ param(
[string]$PlanFile = "task_plan.md"
)
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
if ($env:PLANNING_DISABLED -eq '1') { exit 0 }
if (-not (Test-Path $PlanFile)) {
Write-Host '[planning-with-files-ar] لم يتم العثور على task_plan.md — لا توجد جلسة تخطيط نشطة.'
exit 0
@@ -3,6 +3,10 @@
# ينهي دائمًا برمز خروج 0 — يستخدم stdout للإبلاغ عن الحالة
# يُستدعى بواسطة خطاف Stop للإبلاغ عن حالة اكتمال المهمة
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
+1 -1
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
metadata:
version: "3.2.0"
version: "3.4.0"
---
# Dateiplanungssystem
@@ -6,6 +6,10 @@ param(
[string]$PlanFile = "task_plan.md"
)
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
if ($env:PLANNING_DISABLED -eq '1') { exit 0 }
if (-not (Test-Path $PlanFile)) {
Write-Host '[planning-with-files-de] task_plan.md nicht gefunden — keine aktive Planungssitzung.'
exit 0
@@ -3,6 +3,10 @@
# Immer mit Exit-Code 0 beenden — Status über stdout melden
# Wird vom Stop-Hook aufgerufen, um Aufgabenabschlussstatus zu melden
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
+1 -1
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
metadata:
version: "3.2.0"
version: "3.4.0"
---
# Sistema de Planificación con Archivos
@@ -6,6 +6,10 @@ param(
[string]$PlanFile = "task_plan.md"
)
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
if ($env:PLANNING_DISABLED -eq '1') { exit 0 }
if (-not (Test-Path $PlanFile)) {
Write-Host '[planning-with-files-es] No se encontró task_plan.md — no hay sesión de planificación activa.'
exit 0
@@ -3,6 +3,10 @@
# Siempre salir con código 0 — usar stdout para informar el estado
# Llamado por el hook Stop para informar el estado de finalización de la tarea
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
+1 -1
View File
@@ -29,7 +29,7 @@ hooks:
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
metadata:
version: "3.2.0"
version: "3.4.0"
---
@@ -6,6 +6,10 @@ param(
[string]$PlanFile = "task_plan.md"
)
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
if ($env:PLANNING_DISABLED -eq '1') { exit 0 }
if (-not (Test-Path $PlanFile)) {
Write-Host '[planning-with-files] 未找到 task_plan.md — 没有进行中的规划会话。'
exit 0
@@ -3,6 +3,10 @@
# 始终以退出码 0 结束 — 使用标准输出报告状态
# 由 Stop 钩子调用以报告任务完成状态
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
+1 -1
View File
@@ -29,7 +29,7 @@ hooks:
command: "RESOLVED=\"\"; SCOPE=\"\"; SLUG_RE='^[A-Za-z0-9_][A-Za-z0-9._-]*$'; if [ -n \"${PLAN_ID:-}\" ] && printf \"%s\" \"$PLAN_ID\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${PLAN_ID}\" ]; then RESOLVED=\".planning/${PLAN_ID}\"; SCOPE=\"scoped\"; elif [ -f .planning/.active_plan ]; then AP=$(tr -d '\\r\\n[:space:]' < .planning/.active_plan 2>/dev/null); if [ -n \"$AP\" ] && printf \"%s\" \"$AP\" | grep -Eq \"$SLUG_RE\" && [ -d \".planning/${AP}\" ]; then RESOLVED=\".planning/${AP}\"; SCOPE=\"scoped\"; fi; fi; if [ -z \"$RESOLVED\" ] && [ -d .planning ]; then NEWEST=\"\"; NEWEST_MT=0; for d in .planning/*/; do d=\"${d%/}\"; n=$(basename \"$d\"); case \"$n\" in .*) continue;; esac; printf \"%s\" \"$n\" | grep -Eq \"$SLUG_RE\" || continue; [ -f \"$d/task_plan.md\" ] || continue; m=$(stat -c '%Y' \"$d\" 2>/dev/null || stat -f '%m' \"$d\" 2>/dev/null || date -r \"$d\" +%s 2>/dev/null || echo 0); if [ \"$m\" -gt \"$NEWEST_MT\" ] 2>/dev/null; then NEWEST_MT=\"$m\"; NEWEST=\"$d\"; fi; done; [ -n \"$NEWEST\" ] && { RESOLVED=\"$NEWEST\"; SCOPE=\"scoped\"; }; fi; if [ -z \"$RESOLVED\" ] && [ -f task_plan.md ]; then RESOLVED=\".\"; SCOPE=\"root\"; fi; [ -z \"$RESOLVED\" ] && exit 0; if [ \"$SCOPE\" = \"root\" ]; then PLAN_FILE=\"task_plan.md\"; PROGRESS_FILE=\"progress.md\"; ATTEST=\"\"; [ -f .plan-attestation ] && ATTEST=$(tr -d '\\r\\n[:space:]' < .plan-attestation 2>/dev/null); else PLAN_FILE=\"${RESOLVED}/task_plan.md\"; PROGRESS_FILE=\"${RESOLVED}/progress.md\"; ATTEST=\"\"; [ -f \"${RESOLVED}/.attestation\" ] && ATTEST=$(tr -d '\\r\\n[:space:]' < \"${RESOLVED}/.attestation\" 2>/dev/null); fi; [ -f \"$PLAN_FILE\" ] || exit 0; TAMPERED=0; ACTUAL=\"\"; if [ -n \"$ATTEST\" ]; then CD=\"${TMPDIR:-/tmp}/pwf-sha\"; mkdir -p \"$CD\" 2>/dev/null; KEY=$(printf \"%s\" \"$PLAN_FILE\" | { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } | awk '{print $1}' | cut -c1-16); MT=$(stat -c '%Y' \"$PLAN_FILE\" 2>/dev/null || stat -f '%m' \"$PLAN_FILE\" 2>/dev/null || date -r \"$PLAN_FILE\" +%s 2>/dev/null || echo 0); CF=\"$CD/$KEY\"; CM=\"\"; CS=\"\"; if [ -f \"$CF\" ]; then CM=$(sed -n 1p \"$CF\" 2>/dev/null); CS=$(sed -n 2p \"$CF\" 2>/dev/null); fi; if [ -n \"$MT\" ] && [ \"$MT\" = \"$CM\" ] && [ -n \"$CS\" ]; then ACTUAL=\"$CS\"; else ACTUAL=$( (sha256sum \"$PLAN_FILE\" 2>/dev/null || shasum -a 256 \"$PLAN_FILE\" 2>/dev/null) | awk '{print $1}'); [ -n \"$ACTUAL\" ] && [ -n \"$MT\" ] && printf \"%s\\n%s\\n\" \"$MT\" \"$ACTUAL\" > \"$CF\" 2>/dev/null; fi; [ \"$ACTUAL\" != \"$ATTEST\" ] && TAMPERED=1; fi; echo '[planning-with-files] PreCompact: context compaction is about to occur.'; echo 'Before compaction completes: ensure progress.md captures recent actions and task_plan.md status reflects current phase.'; echo 'task_plan.md, findings.md, progress.md remain on disk and will be re-read after compaction.'; [ -n \"$ATTEST\" ] && echo \"Plan-SHA256 at compaction: $ATTEST\"; exit 0"
metadata:
version: "3.2.0"
version: "3.4.0"
---
@@ -6,6 +6,10 @@ param(
[string]$PlanFile = "task_plan.md"
)
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
if ($env:PLANNING_DISABLED -eq '1') { exit 0 }
if (-not (Test-Path $PlanFile)) {
Write-Host '[planning-with-files] 未找到 task_plan.md — 沒有進行中的規劃會話。'
exit 0
@@ -3,6 +3,10 @@
# 始終以退出碼 0 結束 — 使用標準輸出回報狀態
# 由 Stop 鉤子呼叫以回報任務完成狀態
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
+1 -1
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "SH=\"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.2.0"
version: "3.4.0"
---
# Planning with Files
@@ -20,6 +20,10 @@ param(
[switch]$Gate
)
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
if ($env:PLANNING_DISABLED -eq '1') { exit 0 }
if ($PlanFile -ne "") {
$PlanDir = Split-Path -Parent $PlanFile
if ($PlanDir -eq "") { $PlanDir = "." }
@@ -30,6 +30,10 @@
# interactive terminal (TTY) is skipped entirely. No data on stdin is treated
# as stop_hook_active=false.
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
GATE=0
PLAN_FILE=""
for _arg in "$@"; do
@@ -12,6 +12,10 @@
set -u
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd 2>/dev/null)" || SCRIPT_DIR="."
TARGET="${SCRIPT_DIR}/check-complete.sh"
@@ -21,6 +21,10 @@
set -u
# issue #195: per-invocation opt-out (PLANNING_DISABLED=1) for one-shot/CI
# sessions that share a cwd with a plan but never opted into it.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
CONTEXT="userprompt"
for arg in "$@"; do
case "$arg" in
+8
View File
@@ -32,6 +32,14 @@ class PiDocsHookSupportTests(unittest.TestCase):
self.assertIn("cache-safe", text)
self.assertIn("parity", text)
def test_docs_describe_plan_execute_confirmation(self) -> None:
text = PI_DOC.read_text(encoding="utf-8")
readme = PI_SKILL_README.read_text(encoding="utf-8")
self.assertIn("/plan-execute", text)
self.assertIn("/plan-execute", readme)
self.assertIn("passive", text)
self.assertIn("passive", readme)
if __name__ == "__main__":
unittest.main()
+4
View File
@@ -52,6 +52,10 @@ class PiExtensionCapabilitiesTests(unittest.TestCase):
text = self._read(CONSTANTS_TS)
self.assertRegex(text, r"AUTO_CONTINUE_LIMIT\s*=\s*3")
def test_plan_execute_command_is_registered(self) -> None:
text = self._read(RUNTIME_TS)
self.assertIn('pi.registerCommand("plan-execute"', text)
def test_tampered_blocking_message_exists(self) -> None:
text = self._read(CONSTANTS_TS)
self.assertIn("PLAN TAMPERED", text)
+159
View File
@@ -0,0 +1,159 @@
"""Issue #195: PLANNING_DISABLED=1 per-invocation opt-out.
A one-shot session (codex exec, CI bot, sub-orchestrator) that merely shares a
cwd with an incomplete plan must be able to opt out of every hook: no plan
injection, no stop followup, no plan-file mutation. These tests run the real
hook scripts in a temp dir containing a legacy root task_plan.md (the exact
attachment path the issue reports) with and without the env var.
"""
from __future__ import annotations
import os
import subprocess
import sys
import tempfile
import unittest
from pathlib import Path
REPO = Path(__file__).resolve().parent.parent
CODEX_HOOKS = REPO / ".codex" / "hooks"
SCRIPTS = REPO / "scripts"
PLAN = "# Test Plan\n### Phase 1: something\n**Status:** in_progress\n"
def run_sh(script: Path, cwd: Path, disabled: bool) -> subprocess.CompletedProcess:
env = dict(os.environ)
env.pop("PLANNING_DISABLED", None)
if disabled:
env["PLANNING_DISABLED"] = "1"
return subprocess.run(
["sh", str(script)],
cwd=str(cwd),
env=env,
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=60,
)
class PlanningDisabledOptOutTests(unittest.TestCase):
def setUp(self) -> None:
self._tmp = tempfile.TemporaryDirectory()
self.cwd = Path(self._tmp.name)
(self.cwd / "task_plan.md").write_text(PLAN, encoding="utf-8")
(self.cwd / "progress.md").write_text("progress line\n", encoding="utf-8")
def tearDown(self) -> None:
self._tmp.cleanup()
# --- Codex hooks (the platform #195 reports against) ---
def test_codex_user_prompt_submit_stays_silent_when_disabled(self) -> None:
baseline = run_sh(CODEX_HOOKS / "user-prompt-submit.sh", self.cwd, disabled=False)
self.assertIn("ACTIVE PLAN", baseline.stdout)
disabled = run_sh(CODEX_HOOKS / "user-prompt-submit.sh", self.cwd, disabled=True)
self.assertEqual(disabled.stdout.strip(), "")
self.assertEqual(disabled.returncode, 0)
def test_codex_stop_emits_no_followup_when_disabled(self) -> None:
baseline = run_sh(CODEX_HOOKS / "stop.sh", self.cwd, disabled=False)
self.assertIn("followup_message", baseline.stdout)
disabled = run_sh(CODEX_HOOKS / "stop.sh", self.cwd, disabled=True)
self.assertEqual(disabled.stdout.strip(), "")
self.assertEqual(disabled.returncode, 0)
def test_codex_pre_tool_use_still_allows_but_skips_context(self) -> None:
disabled = run_sh(CODEX_HOOKS / "pre-tool-use.sh", self.cwd, disabled=True)
self.assertIn('"decision": "allow"', disabled.stdout)
self.assertEqual(disabled.stderr.strip(), "")
def test_codex_post_tool_use_stays_silent_when_disabled(self) -> None:
disabled = run_sh(CODEX_HOOKS / "post-tool-use.sh", self.cwd, disabled=True)
self.assertEqual(disabled.stdout.strip(), "")
def test_codex_session_start_stays_silent_when_disabled(self) -> None:
disabled = run_sh(CODEX_HOOKS / "session-start.sh", self.cwd, disabled=True)
self.assertEqual(disabled.stdout.strip(), "")
def test_codex_pre_compact_stays_silent_when_disabled(self) -> None:
disabled = run_sh(CODEX_HOOKS / "pre-compact.sh", self.cwd, disabled=True)
self.assertEqual(disabled.stdout.strip(), "")
def test_codex_adapter_reports_not_attached_when_disabled(self) -> None:
sys.path.insert(0, str(CODEX_HOOKS))
try:
import codex_hook_adapter as adapter
finally:
sys.path.pop(0)
old = os.environ.pop("PLANNING_DISABLED", None)
try:
self.assertTrue(adapter.is_session_attached(self.cwd, None))
os.environ["PLANNING_DISABLED"] = "1"
self.assertFalse(adapter.is_session_attached(self.cwd, None))
finally:
os.environ.pop("PLANNING_DISABLED", None)
if old is not None:
os.environ["PLANNING_DISABLED"] = old
# --- Canonical dispatchers (Claude Code and mirrors) ---
def test_inject_plan_stays_silent_when_disabled(self) -> None:
baseline = run_sh(SCRIPTS / "inject-plan.sh", self.cwd, disabled=False)
self.assertIn("ACTIVE PLAN", baseline.stdout)
disabled = run_sh(SCRIPTS / "inject-plan.sh", self.cwd, disabled=True)
self.assertEqual(disabled.stdout.strip(), "")
def test_gate_stop_stays_silent_when_disabled(self) -> None:
disabled = run_sh(SCRIPTS / "gate-stop.sh", self.cwd, disabled=True)
self.assertEqual(disabled.stdout.strip(), "")
self.assertEqual(disabled.returncode, 0)
def test_check_complete_stays_silent_when_disabled(self) -> None:
baseline = run_sh(SCRIPTS / "check-complete.sh", self.cwd, disabled=False)
self.assertNotEqual(baseline.stdout.strip(), "")
disabled = run_sh(SCRIPTS / "check-complete.sh", self.cwd, disabled=True)
self.assertEqual(disabled.stdout.strip(), "")
# --- Acceptance criterion from #195: plan files byte-for-byte unchanged ---
def test_plan_files_unchanged_after_disabled_hook_pass(self) -> None:
for script in [
CODEX_HOOKS / "session-start.sh",
CODEX_HOOKS / "user-prompt-submit.sh",
CODEX_HOOKS / "pre-tool-use.sh",
CODEX_HOOKS / "post-tool-use.sh",
CODEX_HOOKS / "stop.sh",
CODEX_HOOKS / "pre-compact.sh",
SCRIPTS / "inject-plan.sh",
SCRIPTS / "gate-stop.sh",
SCRIPTS / "check-complete.sh",
]:
run_sh(script, self.cwd, disabled=True)
self.assertEqual((self.cwd / "task_plan.md").read_text(encoding="utf-8"), PLAN)
self.assertEqual(
(self.cwd / "progress.md").read_text(encoding="utf-8"), "progress line\n"
)
# --- Every distributed copy carries the guard ---
def test_all_check_complete_copies_carry_the_guard(self) -> None:
copies = list(REPO.glob("**/check-complete.sh")) + list(
REPO.glob("**/check-complete.ps1")
)
self.assertGreater(len(copies), 10)
for copy in copies:
if "node_modules" in copy.parts:
continue
text = copy.read_text(encoding="utf-8", errors="replace")
self.assertIn(
"PLANNING_DISABLED",
text,
f"missing opt-out guard: {copy.relative_to(REPO)}",
)
if __name__ == "__main__":
unittest.main()