Compare commits

...
2 Commits
Author SHA1 Message Date
OthmanAdi 0fb67596fa release: v3.16.0
Version bumped to 3.16.0 across the 20 tracked parity targets plus the ClawHub
stage. The OpenCode plugin package stays at 1.0.1 and the Pi extension at
1.2.5: this cycle touched hooks/ and .codex/hooks/, neither package.

CHANGELOG entry for #239 including the two scope calls stated rather than left
to be discovered (FileChanged deferred, the standalone skill route unchanged);
README releases-table row; Raymond Manaloto's CONTRIBUTORS entry extended with
#239. Suite size pinned at 706 in README and llms.txt with its guard.
2026-09-03 01:16:42 +02:00
OthmanAdi eb8af2f02f fix(hooks): send the PostToolUse nudge to the model, once per turn, off read-only tools
closes #239, reported by Raymond Manaloto (@sortakool)

The progress reminder is addressed to Claude:

    [planning-with-files] Update progress.md with what you just did. ...

hooks/claude-hook.sh emitted it as systemMessage, which Claude Code documents
as a warning shown to the USER. So the person saw the instruction after every
Write, Edit and Bash call for a whole session, and the model it is written for
never saw it once. emit_session_start eleven lines above already emitted
hookSpecificOutput.additionalContext for its own event, so the correct shape
was in the same file the whole time. .codex/hooks/post_tool_use.py had the
identical defect, next to a pre_tool_use.py and a run_sh.py that already used
the right shape.

Three defects, one line apart, fixed together:

1. The field. Both routes now emit additionalContext under hookSpecificOutput
   with "hookEventName": "PostToolUse".

2. The throttle. Once per turn rather than once per tool call. The string is a
   constant, so every repeat after the first carries no information: it names
   no tool, no file and no phase. UserPromptSubmit and SessionStart fire once
   per turn and clear a marker; the first post-tool fire of the turn sets it.
   The marker lives in the user's private cache under pwf-turn/, never in the
   plan directory, and is keyed on the plan path plus PWF_SESSION_ID so two
   sessions sharing a plan do not silence each other. A cache root that cannot
   be created skips the throttle rather than the reminder, so a broken cache
   cannot quietly remove the signal instead of the noise.

3. The matcher. Bash comes off PostToolUse on all three manifests: ls, git
   status and grep were tripping a "you changed something, record it" nudge.
   hooks/hooks.json goes to Write|Edit and both Codex manifests to
   apply_patch|Edit|Write. PreToolUse keeps Bash, because a plan reminder
   before a shell command is a different and wanted behaviour. The standalone
   skill route already used Write|Edit, which is further evidence the wider
   matchers were drift rather than intent.

Fixing this surfaced a fourth thing. active_plan_dir() in hooks/claude-hook.sh
resolves through the shared resolver and then fell back to the legacy root
task_plan.md: the #237 fallback removed from the script and Codex routes in
v3.15.0 and missed on the plugin dispatcher. A rejected PLAN_ID or
PWF_PLAN_ROOT now stops there too.

Deliberately not in this change: FileChanged, which would catch a Bash command
that rewrites a file, is a new event surface with its own behaviour and belongs
in a release where it can be tested on its own. The standalone skill route
still emits the sentence as plain stdout from a YAML frontmatter scalar with no
throttle; it already carries the narrow matcher so the volume reported here
never applied to it, and giving it the throttle means either putting cache-key
logic inside a hook scalar or routing it through a new script context across
eleven SKILL.md files.

Tests: 10 in tests/test_post_tool_nudge.py, driving both routes as processes
rather than asserting on source. One proves the two Codex scripts agree on the
marker key by asserting the re-arm deletes the exact file the throttle wrote:
they derive it independently and one resolves a PWF_PLAN_ROOT pin while the
other does not, so a divergence would leave the nudge firing once per session
with nothing in any log.
2026-09-03 01:16:16 +02:00
32 changed files with 418 additions and 35 deletions
+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.15.0"
version: "3.16.0"
---
# Planning with Files
+1 -1
View File
@@ -10,7 +10,7 @@
"name": "planning-with-files",
"source": "./",
"description": "Persistent project planning files with lifecycle hooks that inject selected plan context. Automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs commands declared in Markdown. No network upload path. Installs across 60+ agents.",
"version": "3.15.0"
"version": "3.16.0"
}
]
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.15.0",
"version": "3.16.0",
"description": "Persistent project planning files with lifecycle hooks that inject selected plan context. Automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs commands declared in Markdown. No network upload path. Works across 60+ agents and includes Arabic, German, Spanish, Simplified Chinese, and Traditional Chinese.",
"author": {
"name": "OthmanAdi",
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"${CODEBUDDY_PLUGIN_ROOT}/scripts/inject-plan.sh\" \"$HOME/.codebuddy/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.15.0"
version: "3.16.0"
---
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.15.0",
"version": "3.16.0",
"description": "Persistent project planning for Codex. Opt-in lifecycle hooks inject selected plan context; automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs Markdown-declared commands. No network upload path.",
"author": {
"name": "OthmanAdi",
+1 -1
View File
@@ -50,7 +50,7 @@
],
"PostToolUse": [
{
"matcher": "Bash|apply_patch|Edit|Write",
"matcher": "apply_patch|Edit|Write",
"hooks": [
{
"type": "command",
+39 -2
View File
@@ -13,7 +13,44 @@ PLAN_DIR="$(sh "${HOOK_DIR}/resolve-plan-dir.sh" 2>/dev/null)"
[ -z "$PLAN_DIR" ] && [ -n "${PLAN_ID:-}" ] && exit 0
PLAN_FILE="${PLAN_DIR:+${PLAN_DIR}/}task_plan.md"
if [ -f "$PLAN_FILE" ]; then
echo "[planning-with-files] Update progress.md with what you just did. If a phase is now complete, update task_plan.md status."
[ -f "$PLAN_FILE" ] || exit 0
# --- Once-per-turn throttle (issue #239). ---
# The reminder is a constant string, so every repeat after the first in a turn
# carries no information: it names no tool, no file and no phase. The Codex
# matcher fired on every shell command, so a session running twenty of them got
# twenty identical lines. user-prompt-submit.sh fires once per turn and clears
# this marker; the first post-tool fire of the turn sets it.
#
# The marker lives in the user's private cache, never in the plan directory:
# that directory is shared project state. Cache root and key derivation match
# hooks/claude-hook.sh and the slots inject-plan.sh already uses, so the two
# routes throttle the same way. When no cache root can be created the throttle
# is skipped rather than the nudge suppressed, so a broken cache cannot
# silently remove the reminder.
if [ -n "${XDG_CACHE_HOME:-}" ]; then
TURN_ROOT="${XDG_CACHE_HOME}/pwf-turn"
elif [ -n "${HOME:-}" ]; then
TURN_ROOT="${HOME}/.cache/pwf-turn"
else
TURN_ROOT="${TMPDIR:-/tmp}/pwf-turn"
fi
TURN_MARKER=""
if mkdir -p "$TURN_ROOT" 2>/dev/null; then
case "$PLAN_FILE" in
/*|[A-Za-z]:*|\\\\*) TURN_KEY_SRC="$PLAN_FILE" ;;
*) TURN_KEY_SRC="${PWD}/${PLAN_FILE}" ;;
esac
TURN_KEY_SRC="${TURN_KEY_SRC}|${PWF_SESSION_ID:-}"
TURN_KEY=$(printf '%s' "$TURN_KEY_SRC" \
| { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } \
| awk '{print $1}' | cut -c1-16)
[ -n "$TURN_KEY" ] && TURN_MARKER="${TURN_ROOT}/${TURN_KEY}"
fi
if [ -n "$TURN_MARKER" ]; then
[ -e "$TURN_MARKER" ] && exit 0
: > "$TURN_MARKER" 2>/dev/null || :
fi
echo "[planning-with-files] Update progress.md with what you just did. If a phase is now complete, update task_plan.md status."
exit 0
+12 -1
View File
@@ -15,7 +15,18 @@ def main() -> None:
stdout, _ = adapter.run_shell_script("post-tool-use.sh", root)
if stdout:
adapter.emit_json({"systemMessage": stdout})
# The nudge is addressed to Claude, so it belongs in the model's
# context, not in a systemMessage (issue #239). systemMessage is a
# warning shown to the USER, so the instruction never reached the model
# while the person saw it after every matching tool call.
# pre_tool_use.py and run_sh.py already emit this shape for their own
# events; this path had simply never been moved over.
adapter.emit_json({
"hookSpecificOutput": {
"hookEventName": "PostToolUse",
"additionalContext": stdout,
}
})
if __name__ == "__main__":
+31
View File
@@ -94,6 +94,37 @@ else
fi
[ -f "$PLAN_FILE" ] || exit 0
# --- Re-arm the once-per-turn PostToolUse nudge (issue #239). ---
# One user message is one turn, and this hook fires once per turn, so clearing
# the marker here is what makes the nudge appear once after the first write
# instead of after every matching tool call.
#
# The key is computed from post-tool-use.sh's OWN plan-file expression, not
# from $PLAN_FILE above. This hook resolves a PWF_PLAN_ROOT pin and that one
# does not, so the two spellings diverge under a pin; keying off the shared
# expression keeps both sides on one marker. A mismatch here would not be
# loud: the marker would never be cleared and the nudge would fire once per
# session instead of once per turn.
TURN_PLAN_FILE="${PLAN_DIR:+${PLAN_DIR}/}task_plan.md"
if [ -n "${XDG_CACHE_HOME:-}" ]; then
TURN_ROOT="${XDG_CACHE_HOME}/pwf-turn"
elif [ -n "${HOME:-}" ]; then
TURN_ROOT="${HOME}/.cache/pwf-turn"
else
TURN_ROOT="${TMPDIR:-/tmp}/pwf-turn"
fi
if [ -d "$TURN_ROOT" ]; then
case "$TURN_PLAN_FILE" in
/*|[A-Za-z]:*|\\\\*) TURN_KEY_SRC="$TURN_PLAN_FILE" ;;
*) TURN_KEY_SRC="${PWD}/${TURN_PLAN_FILE}" ;;
esac
TURN_KEY_SRC="${TURN_KEY_SRC}|${PWF_SESSION_ID:-}"
TURN_KEY=$(printf '%s' "$TURN_KEY_SRC" \
| { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } \
| awk '{print $1}' | cut -c1-16)
[ -n "$TURN_KEY" ] && rm -f -- "${TURN_ROOT}/${TURN_KEY}" 2>/dev/null || :
fi
# Session isolation: if .planning/sessions/ exists, only attached sessions see
# plan context. Absence of the sessions dir means legacy single-session mode —
# all sessions in the cwd receive context to preserve backward compatibility.
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.codex/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.15.0"
version: "3.16.0"
---
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.cursor/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.15.0"
version: "3.16.0"
---
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.factory/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.15.0"
version: "3.16.0"
---
# Planning with Files
+1 -1
View File
@@ -2,7 +2,7 @@
name: planning-with-files
description: "Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls."
metadata:
version: "3.15.0"
version: "3.16.0"
hermes:
tags: [planning, long-running-tasks, context-engineering, workflow]
---
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.mastracode/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.15.0"
version: "3.16.0"
---
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.config/opencode/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.opencode/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.15.0"
version: "3.16.0"
---
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.15.0",
"version": "3.16.0",
"description": "Persistent project planning with selected context injection. Automatic recovery uses project files only; explicit catchup modes read same-project local session records for aggregate counts or bounded replay. The host-aware gate never runs Markdown-declared commands. No network upload path. Ships the skill plus a Pi Coding Agent extension.",
"keywords": [
"pi-package",
+21
View File
@@ -4,6 +4,27 @@ All notable changes to this project will be documented in this file.
## [Unreleased]
## [3.16.0] - 2026-09-03
The PostToolUse progress reminder was addressed to Claude and delivered to the user instead, on every matching tool call, with `Bash` in the matcher. Reported by @sortakool in #239, filed shortly after #236 to #238 and fixed on its own.
### Fixed
- **The PostToolUse nudge never reached the model (closes #239, reported by @sortakool).** `hooks/claude-hook.sh:110` emitted "Update progress.md with what you just did" as `systemMessage`, which Claude Code documents as a warning shown to the user. So the person saw the instruction after every `Write`, `Edit` and `Bash` call and the model, which the sentence is written for, never saw it once. `emit_session_start` eleven lines above already emitted `hookSpecificOutput.additionalContext` for its own event, so the correct shape was in the same file the whole time. Both the plugin dispatcher and `.codex/hooks/post_tool_use.py` now emit `additionalContext` with `"hookEventName": "PostToolUse"`; the Codex adapter's `pre_tool_use.py` and `run_sh.py` already used that shape for their events.
- **The nudge is now once per turn rather than once per tool call.** The string is a constant, so every repeat after the first carries no information: it names no tool, no file and no phase. UserPromptSubmit and SessionStart fire once per turn and clear a marker; the first post-tool fire of the turn sets it. The marker lives in the user's private cache under `pwf-turn/`, never in the plan directory, and is keyed on the plan path plus `PWF_SESSION_ID` so two sessions sharing a plan do not silence each other. A cache root that cannot be created skips the throttle rather than the reminder, so a broken cache cannot quietly remove it.
- **`Bash` came off the PostToolUse matchers.** `ls`, `git status` and `grep` were tripping a "you changed something, record it" reminder. `hooks/hooks.json` goes to `Write|Edit` and both Codex manifests go to `apply_patch|Edit|Write`. PreToolUse keeps `Bash`: a plan reminder before a shell command is a different and wanted behavior. The standalone skill route already used `Write|Edit`, which is further evidence the wider matcher was drift rather than intent.
- **The plugin dispatcher still had the #237 fallback.** `active_plan_dir()` in `hooks/claude-hook.sh` resolves through the shared resolver and then fell back to the legacy root `task_plan.md`, the fallback v3.15.0 removed from the script and Codex routes but not from this one. Found while fixing #239. A rejected `PLAN_ID` or `PWF_PLAN_ROOT` now stops there too.
### Verification
- 10 new tests in `tests/test_post_tool_nudge.py`, driving both routes as processes. Coverage includes the field, the once-per-turn behavior through a real re-arm, session-start as a second re-arm, two session ids not silencing each other, a broken cache root still emitting, and every matcher in all three manifests.
- One test earns its place by proving key agreement through deletion: the two Codex scripts derive the marker key independently and one of them resolves a `PWF_PLAN_ROOT` pin while the other does not. A divergence there would leave the marker uncleared and silently degrade the nudge to once per session, so the re-arm is asserted to remove the exact file the throttle wrote.
### Not changed
- The standalone skill route emits the same sentence as plain stdout from a YAML frontmatter scalar, with no throttle. It already carries the narrower `Write|Edit` matcher, so the spam this issue is about never applied to it, and giving it the throttle means either embedding cache-key logic in a hook scalar or routing it through a new script context across eleven SKILL.md files. Both are real changes that belong in a release where they can be tested on their own rather than appended to a fix.
- `FileChanged` was suggested in the issue as a way to catch a `Bash` command that rewrites a file. It is a new event surface with its own behavior and is deliberately left for its own release.
### Thanks
- Raymond, for tracing all three defects to the line and checking the Codex route before filing, and for confirming there was no user-side workaround rather than leaving it to be guessed at (#239).
## [3.15.0] - 2026-09-02
Three selector and policy defects reported by @sortakool, all reproduced here before any code changed. Two of them let a session work on a plan nobody selected, and the third made the diagnostic that should have caught them report PASS. A minor rather than a patch because two behaviors change on purpose: a `PLAN_ID` that does not resolve now refuses instead of picking another plan, and a slug plan can no longer start below a project's committed `.mode`.
+1 -1
View File
@@ -7,7 +7,7 @@ authors:
- family-names: Adi
given-names: Ahmad Othman Ammar
alias: OthmanAdi
version: "3.15.0"
version: "3.16.0"
date-released: "2026-08-31"
license: MIT
url: "https://github.com/OthmanAdi/planning-with-files"
+3 -2
View File
@@ -106,12 +106,13 @@ These amazing people have contributed code, documentation, or significant improv
### Other Contributors
- **[Raymond Manaloto](https://github.com/sortakool)** - [Issue #234](https://github.com/OthmanAdi/planning-with-files/issues/234), [Issue #236](https://github.com/OthmanAdi/planning-with-files/issues/236), [Issue #237](https://github.com/OthmanAdi/planning-with-files/issues/237), [Issue #238](https://github.com/OthmanAdi/planning-with-files/issues/238)
- **[Raymond Manaloto](https://github.com/sortakool)** - [Issue #234](https://github.com/OthmanAdi/planning-with-files/issues/234), [Issue #236](https://github.com/OthmanAdi/planning-with-files/issues/236), [Issue #237](https://github.com/OthmanAdi/planning-with-files/issues/237), [Issue #238](https://github.com/OthmanAdi/planning-with-files/issues/238), [Issue #239](https://github.com/OthmanAdi/planning-with-files/issues/239)
- Reproduced the nested attestation failure and traced it to the fallback from slug mode to legacy mode when the helper runs inside `.planning/<slug>/`
- Found that `plan-doctor.sh` matched its control strings against the injected plan body, so a plan quoting one of them reported a false tamper warning, and that a stale literal at `:92` made a fully dark-hooks state report PASS. Supplied the structural alternative that replaced the string matching, and the four test arms
- Showed that a `PLAN_ID` of valid slug shape naming no directory fell through to another plan, which then got attested at rc=0, with a control arm proving the probe could return the right plan
- Showed that a slug plan with no `.mode` bypassed a project's committed root `.mode`, with a control arm removing the slug directory to prove it was a bypass rather than a mode that was never armed
- **Impact:** Attestation and injection follow the plan the operator named or refuse; a project's `.mode` is a floor a plan cannot start below; and `/plan-doctor` classifies on the data framing, so a reworded banner degrades to a warning instead of a silent PASS
- Traced the PostToolUse progress reminder to `systemMessage`, a field Claude Code delivers to the user, so an instruction written for the model reached the person instead on every matching tool call, and checked the Codex adapter for the same defect before filing
- **Impact:** Attestation and injection follow the plan the operator named or refuse; a project's `.mode` is a floor a plan cannot start below; `/plan-doctor` classifies on the data framing, so a reworded banner degrades to a warning instead of a silent PASS; and the progress reminder reaches the model, once per turn, without firing on read-only shell commands
- **[@lowmiaq-gmail](https://github.com/lowmiaq-gmail)** - [PR #233](https://github.com/OthmanAdi/planning-with-files/pull/233) / [Issue #232](https://github.com/OthmanAdi/planning-with-files/issues/232)
- Reported that direct help flags were parsed as project names, then supplied a focused POSIX-shell fix and regression covering both `-h` and `--help` against an empty working directory
+2 -1
View File
@@ -68,7 +68,7 @@ The transcript is illustrative; the `===BEGIN PLAN DATA===` block is the skill's
| Plan files | **3** |
| Agents covered | **60+** |
| Pass rate (with skill) | **96.7%** |
| Test suite | **696 tests** |
| Test suite | **706 tests** |
| Survives `/clear` | **yes** |
## Built for long-running agent tasks
@@ -354,6 +354,7 @@ One hook fire measures 289ms wall-clock since the v3.6.0 optimization, down from
| Version | Highlights |
|---------|------------|
| **v3.16.0** | **The PostToolUse progress reminder was shown to you and never to Claude** (closes #239, reported by @sortakool). It was emitted as `systemMessage`, which Claude Code delivers to the user, so a sentence addressed to the model reached the person instead, after every `Write`, `Edit` and `Bash` call for a whole session. Both the plugin dispatcher and the Codex adapter now emit `hookSpecificOutput.additionalContext`, the shape the session-start path in the same file already used. The reminder is also throttled to once per turn instead of once per tool call, and `Bash` is off the PostToolUse matchers so `ls` and `git status` stop tripping a "record what you changed" nudge. PreToolUse keeps `Bash`. Fixing this surfaced one more copy of the #237 fallback in the plugin dispatcher, now closed. |
| **v3.15.0** | **A mistyped `PLAN_ID` used to attest and inject a different plan, and a slug plan could switch off the project's own policy** (closes #237 and #238, both reported by @sortakool). An explicit `PLAN_ID` is now a binding in every resolver, shell, PowerShell, Hermes, OpenCode and Pi: it resolves or it stops, and every consumer that reads or writes the selected plan says which selector refused instead of quietly using the root plan. A project's root `.mode` is now a floor rather than a default that slug scope replaces, so creating a plan can no longer drop a committed attestation requirement or completion gate; a slug may raise strictness, never lower it. Also fixes `plan-doctor.sh` reporting `PASS injection: emits plan context` on a state where nothing was injected at all (closes #236): classification branches on the `===BEGIN-PWF-DATA` framing rather than substring-matching control strings against the plan body, so a plan quoting one of them no longer trips a false tamper warning and a reworded banner degrades to a warning instead of a silent PASS. 30 new tests, each with its own control arm. |
| **v3.14.0** | **OpenCode becomes a first-class host through its own plugin system** (closes #235, reported by @luyanfeng). New npm plugin `opencode-planning-with-files`: `chat.message` injects the framed plan on every turn, `tool.execute.after` reminds after writes, `experimental.session.compacting` keeps the plan pointer and attestation in the summary, and `session.idle` runs the completion gate in gated mode by re-prompting the session (Tier 2). Tools `pwf_init`, `pwf_status`, `pwf_check`; commands `/pwf`, `/pwf-status`. Same resolver, ambiguity rule, gate table and frame format as the shell route, 22 Vitest tests, verified live in OpenCode 1.18.21. `docs/opencode.md` now names the real install path (`npx skills add -g` lands in `~/.agents/skills/`, which OpenCode reads) and the tier tables stop crediting OpenCode with hooks it never ran. |
| **v3.13.0** | **Hermes Agent becomes a first-class host, CLI and Desktop.** The native plugin now resolves `.planning/<slug>/` plans (the old adapter only saw a root `task_plan.md`), honours `PLAN_ID`, `PWF_PLAN_ROOT` and `PLANNING_DISABLED`, registers `/pwf`, `/pwf-status` and `/plan-status` (the shipped Markdown command files were never loaded by Hermes), bundles the skill, creates gated and autonomous plans with attestation from `/pwf --gated <name>`, and answers Hermes' `pre_verify` hook with the completion gate. Verified in a live Hermes 0.19.1 plugin manager; the Hermes `skills-guard` scanner rates the bundle `SAFE`. Native Windows path fix (`%LOCALAPPDATA%\hermes`). README reorganized: install and platforms first, proof and reference at the bottom, nothing removed. |
+87 -5
View File
@@ -52,11 +52,89 @@ active_plan_dir() {
fi
if [ -n "$_resolved" ] && [ -f "${_resolved}/task_plan.md" ]; then
printf '%s\n' "$_resolved"
elif [ -f task_plan.md ]; then
return 0
fi
# Explicit selectors are bindings, not hints (issue #237). The shared
# resolver emits nothing when it rejected one, and the legacy-root fallback
# below would answer for a plan the operator never named. v3.15.0 closed
# this on the script and Codex routes; the plugin dispatcher reads the same
# resolver and needed the same guard.
if [ -n "${PLAN_ID:-}" ] || [ -n "${PWF_PLAN_ROOT:-}" ]; then
return 0
fi
if [ -f task_plan.md ]; then
printf '%s\n' "."
fi
}
# --- Once-per-turn throttle for the PostToolUse nudge (issue #239). ---
# The progress reminder is worth one appearance after the first write in a turn
# and is pure noise on every tool call after that: the string is constant, so
# repeats carry no information beyond the first. UserPromptSubmit and
# SessionStart fire exactly once per turn, so they clear the marker and the
# first PostToolUse of the turn sets it.
#
# The marker lives in the user's private cache, never in the plan directory:
# that directory is shared project state and a per-session throttle file does
# not belong in a repo. Cache root and key derivation are deliberately the same
# shape inject-plan.sh already uses for its SHA and progress-guard slots, so
# the marker inherits the same cwd-invariance (#212). If no cache root can be
# created the throttle is skipped rather than the nudge suppressed, which keeps
# a broken cache from silently removing the reminder.
turn_marker_path() {
_tm_plan="$1"
if [ -n "${XDG_CACHE_HOME:-}" ]; then
_tm_root="${XDG_CACHE_HOME}/pwf-turn"
elif [ -n "${HOME:-}" ]; then
_tm_root="${HOME}/.cache/pwf-turn"
else
_tm_root="${TMPDIR:-/tmp}/pwf-turn"
fi
mkdir -p "$_tm_root" 2>/dev/null || return 1
case "$_tm_plan" in
/*|[A-Za-z]:*|\\\\*) _tm_key_src="$_tm_plan" ;;
*) _tm_key_src="${PWD}/${_tm_plan}" ;;
esac
# Two sessions sharing one plan must not silence each other's first nudge,
# so the host's session id joins the key whenever it names one.
_tm_key_src="${_tm_key_src}|${PWF_SESSION_ID:-}"
_tm_key=$(printf '%s' "$_tm_key_src" \
| { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } \
| awk '{print $1}' | cut -c1-16)
[ -n "$_tm_key" ] || return 1
printf '%s/%s\n' "$_tm_root" "$_tm_key"
}
clear_turn_marker() {
_ct_plan=$(active_plan_dir) || return 0
[ -n "$_ct_plan" ] || return 0
_ct_marker=$(turn_marker_path "$_ct_plan") || return 0
rm -f -- "$_ct_marker" 2>/dev/null || :
}
# The nudge is addressed to Claude, so it goes into the model's context as
# additionalContext, not to the user as systemMessage (issue #239).
# systemMessage is documented as a warning shown to the USER, so the model
# never received this instruction and the person received it after every
# matching tool call. emit_session_start above already used the correct shape
# for its event; this path had simply never been moved over.
emit_post_tool_nudge() {
[ -f "$RESOLVE_PLAN_DIR" ] || exit 0
_plan_dir=$(active_plan_dir) || exit 0
[ -n "$_plan_dir" ] && [ -f "${_plan_dir}/task_plan.md" ] || exit 0
_marker=$(turn_marker_path "$_plan_dir") || _marker=""
if [ -n "$_marker" ]; then
[ -e "$_marker" ] && exit 0
: > "$_marker" 2>/dev/null || :
fi
_nudge="[planning-with-files] Update progress.md with what you just did. If a phase is now complete, update task_plan.md status."
_encoded=$(printf '%s' "$_nudge" | json_string)
printf '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"%s"}}\n' \
"$_encoded"
}
emit_session_start() {
[ -f "$INJECT_PLAN" ] && [ -f "$RESOLVE_PLAN_DIR" ] || exit 0
_plan_dir=$(active_plan_dir) || exit 0
@@ -95,19 +173,23 @@ case "$EVENT" in
# Startup, resume, clear, and post-compact restoration share the same
# bounded planning context. Catch-up runs first when Python is present.
# With no active plan, both operations remain silent.
# A new session starts a new turn, so any stale throttle marker from a
# previous run of this session id is cleared here as well (#239).
clear_turn_marker
emit_session_start
;;
user-prompt-submit)
# One user message is one turn. Clearing here re-arms the PostToolUse
# nudge exactly once per turn (#239). It runs before emit_context
# because that function exits early on several paths.
clear_turn_marker
emit_context "UserPromptSubmit" "userprompt"
;;
pre-tool-use)
emit_context "PreToolUse" "pretool"
;;
post-tool-use)
[ -f "$RESOLVE_PLAN_DIR" ] || exit 0
_plan_dir=$(active_plan_dir) || exit 0
[ -n "$_plan_dir" ] && [ -f "${_plan_dir}/task_plan.md" ] || exit 0
emit_system_message "[planning-with-files] Update progress.md with what you just did. If a phase is now complete, update task_plan.md status."
emit_post_tool_nudge
;;
pre-compact)
[ -f "$INJECT_PLAN" ] || exit 0
+1 -1
View File
@@ -51,7 +51,7 @@
],
"PostToolUse": [
{
"matcher": "Bash|apply_patch|Edit|Write",
"matcher": "apply_patch|Edit|Write",
"hooks": [
{
"type": "command",
+1 -1
View File
@@ -51,7 +51,7 @@
],
"PostToolUse": [
{
"matcher": "Write|Edit|Bash",
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
+1 -1
View File
@@ -15,7 +15,7 @@
- Category: persistent planning for AI coding agents. Not a memory or retrieval system: it manages planning continuity for the active task.
- Pattern: structured note-taking. Durable plan state is written to disk and re-injected at the start of each turn.
- Evidence: 96.7% workflow-fidelity pass rate with the skill vs 6.7% without in the formal eval; a 696-test suite guards the mechanisms.
- Evidence: 96.7% workflow-fidelity pass rate with the skill vs 6.7% without in the formal eval; a 706-test suite guards the mechanisms.
- Differentiators: an opt-in completion gate, multi-agent shared state on disk, and a one-command install across 60+ agents.
- Problem it solves: context rot and lost plans. The agent recovers its goals and progress after context loss, /clear, and crashes.
- License: MIT.
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files-ar/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.15.0"
version: "3.16.0"
---
# نظام تخطيط الملفات
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files-de/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.15.0"
version: "3.16.0"
---
# Dateiplanungssystem
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files-es/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.15.0"
version: "3.16.0"
---
# Sistema de Planificación con Archivos
+1 -1
View File
@@ -37,7 +37,7 @@ hooks:
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files-zh/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.15.0"
version: "3.16.0"
---
+1 -1
View File
@@ -37,7 +37,7 @@ hooks:
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files-zht/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.15.0"
version: "3.16.0"
---
+1 -1
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "[ -n \"${CLAUDE_PLUGIN_ROOT:-}\" ] && exit 0; 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.15.0"
version: "3.16.0"
---
# Planning with Files
+1 -1
View File
@@ -44,7 +44,7 @@ MONEY_PHRASES = [
]
# Only numbers already public in the repo (README FAQ + docs/evals.md).
PUBLIC_NUMBERS = ["96.7%", "696", "330", "5.0", "13.3"]
PUBLIC_NUMBERS = ["96.7%", "706", "330", "5.0", "13.3"]
# Topics rejected on honesty grounds plus competitor names. Word-bounded so
# e.g. "decline" cannot false-positive on "cline".
+199
View File
@@ -0,0 +1,199 @@
"""The PostToolUse nudge reaches the model, once per turn (issue #239).
The hook emitted an instruction addressed to Claude:
[planning-with-files] Update progress.md with what you just did. ...
as ``systemMessage``, which Claude Code delivers to the USER. So the model
never received the instruction, the person received it after every ``Write``,
``Edit`` and ``Bash`` call for the whole session, and nothing rate-limited it.
``emit_session_start`` in the same file already used the correct
``hookSpecificOutput.additionalContext`` shape for its own event, which is what
made this an oversight rather than a design choice.
Three defects, fixed together and pinned here:
1. wrong field, so the message never reached the model,
2. no throttle, so a constant string repeated per tool call,
3. ``Bash`` in the matcher, so ``ls`` and ``git status`` tripped a
"you changed something" reminder.
The Codex adapter carried the identical defect with a wider matcher, so both
routes are exercised. The throttle marker lives in the user's private cache and
is keyed on the plan path plus the session id; the key-agreement test is the
one that catches a re-arm that silently never fires.
"""
from __future__ import annotations
import json
import os
import shutil
import subprocess
import unittest
from pathlib import Path
REPO_ROOT = Path(__file__).resolve().parents[1]
CLAUDE_HOOK = REPO_ROOT / "hooks" / "claude-hook.sh"
CODEX_HOOKS = REPO_ROOT / ".codex" / "hooks"
NUDGE = "Update progress.md with what you just did"
def have_sh() -> bool:
return shutil.which("sh") is not None
@unittest.skipUnless(have_sh(), "requires a POSIX sh")
class PostToolNudgeTests(unittest.TestCase):
def setUp(self) -> None:
import tempfile
self.tempdir = tempfile.TemporaryDirectory(prefix="pwf-nudge-")
self.root = Path(self.tempdir.name)
(self.root / "task_plan.md").write_text(
"# Task Plan: t\n### Phase 1\n- [ ] work\n", encoding="utf-8"
)
(self.root / "progress.md").write_text("# Progress\n", encoding="utf-8")
self.cache = self.root / "_cache"
self.cache.mkdir()
def tearDown(self) -> None:
self.tempdir.cleanup()
def _env(self, **extra: str) -> dict:
env = os.environ.copy()
for key in ("PLAN_ID", "PWF_PLAN_ROOT", "PLANNING_DISABLED", "PWF_SESSION_ID"):
env.pop(key, None)
env["XDG_CACHE_HOME"] = str(self.cache)
env["CLAUDE_PLUGIN_ROOT"] = str(REPO_ROOT)
env.update(extra)
return env
def _claude(self, event: str, **extra: str) -> str:
return subprocess.run(
["sh", str(CLAUDE_HOOK), event],
cwd=str(self.root), env=self._env(**extra),
capture_output=True, text=True, timeout=180,
).stdout
def _codex(self, script: str, **extra: str) -> str:
return subprocess.run(
["sh", str(CODEX_HOOKS / script)],
cwd=str(self.root), env=self._env(**extra),
capture_output=True, text=True, timeout=180,
).stdout
# --- defect 1: the field ------------------------------------------------
def test_claude_nudge_goes_to_the_model_not_the_user(self):
out = self._claude("post-tool-use")
self.assertNotIn("systemMessage", out)
payload = json.loads(out)
block = payload["hookSpecificOutput"]
self.assertEqual("PostToolUse", block["hookEventName"])
self.assertIn(NUDGE, block["additionalContext"])
def test_codex_nudge_goes_to_the_model_not_the_user(self):
adapter_check = subprocess.run(
["python", "-c", "import ast,sys;ast.parse(open(sys.argv[1],encoding='utf-8').read())",
str(CODEX_HOOKS / "post_tool_use.py")],
capture_output=True, text=True, timeout=60,
)
self.assertEqual(0, adapter_check.returncode, adapter_check.stderr)
source = (CODEX_HOOKS / "post_tool_use.py").read_text(encoding="utf-8")
self.assertIn('"hookEventName": "PostToolUse"', source)
self.assertIn('"additionalContext": stdout', source)
self.assertNotIn('{"systemMessage": stdout}', source)
# --- defect 2: the throttle ---------------------------------------------
def test_claude_nudge_fires_once_per_turn(self):
self.assertIn(NUDGE, self._claude("post-tool-use"))
self.assertEqual("", self._claude("post-tool-use").strip())
self.assertEqual("", self._claude("post-tool-use").strip())
self._claude("user-prompt-submit")
self.assertIn(NUDGE, self._claude("post-tool-use"))
def test_claude_session_start_also_rearms(self):
self.assertIn(NUDGE, self._claude("post-tool-use"))
self.assertEqual("", self._claude("post-tool-use").strip())
self._claude("session-start")
self.assertIn(NUDGE, self._claude("post-tool-use"))
def test_codex_nudge_fires_once_per_turn(self):
self.assertIn(NUDGE, self._codex("post-tool-use.sh"))
self.assertEqual("", self._codex("post-tool-use.sh").strip())
self._codex("user-prompt-submit.sh")
self.assertIn(NUDGE, self._codex("post-tool-use.sh"))
def test_codex_rearm_and_throttle_agree_on_one_marker_slot(self):
"""The failure this catches is silent.
post-tool-use.sh and user-prompt-submit.sh derive the marker key
independently, and the second resolves a PWF_PLAN_ROOT pin while the
first does not. If the two spellings diverged, the marker would never
be cleared and the nudge would degrade to once per SESSION with no
error anywhere.
Agreement is proven by deletion: the re-arm must remove the exact file
the throttle wrote. A leftover slot means it deleted a different key
and the two sides are out of step.
"""
self._codex("post-tool-use.sh")
written = sorted((self.cache / "pwf-turn").glob("*"))
self.assertEqual(1, len(written), "the throttle wrote no marker to agree on")
self._codex("user-prompt-submit.sh")
left = sorted((self.cache / "pwf-turn").glob("*"))
self.assertEqual([], left, f"re-arm deleted a different key, stale slots: {left}")
def test_two_sessions_do_not_silence_each_others_first_nudge(self):
self.assertIn(NUDGE, self._claude("post-tool-use", PWF_SESSION_ID="alpha"))
self.assertEqual("", self._claude("post-tool-use", PWF_SESSION_ID="alpha").strip())
self.assertIn(NUDGE, self._claude("post-tool-use", PWF_SESSION_ID="beta"))
def test_a_broken_cache_root_skips_the_throttle_not_the_nudge(self):
"""Fail toward the reminder, never toward silence."""
env_extra = {"XDG_CACHE_HOME": str(self.root / "task_plan.md")} # a file, not a dir
first = self._claude("post-tool-use", **env_extra)
second = self._claude("post-tool-use", **env_extra)
self.assertIn(NUDGE, first)
self.assertIn(NUDGE, second)
# --- defect 3: the matcher ----------------------------------------------
def test_bash_is_off_the_post_tool_matchers_and_still_on_pre_tool(self):
for manifest in (
REPO_ROOT / "hooks" / "hooks.json",
REPO_ROOT / "hooks" / "codex-hooks.json",
REPO_ROOT / ".codex" / "hooks.json",
):
with self.subTest(manifest=manifest.name):
data = json.loads(manifest.read_text(encoding="utf-8"))
node = data.get("hooks", data)
post = [b.get("matcher", "") for b in node["PostToolUse"]]
self.assertTrue(post, manifest)
for matcher in post:
self.assertNotIn("Bash", matcher)
self.assertIn("Write", matcher)
self.assertIn("Edit", matcher)
# A pre-tool plan reminder before a shell command is a
# different, wanted behaviour and must not be collateral.
for matcher in [b.get("matcher", "") for b in node["PreToolUse"]]:
self.assertIn("Bash", matcher)
# --- the #237 gap this issue exposed in the plugin dispatcher -----------
def test_plugin_dispatcher_honors_a_rejected_plan_id_binding(self):
"""hooks/claude-hook.sh resolves through the shared resolver and then
fell back to the legacy root plan, the fallback v3.15.0 removed from
the script and Codex routes but not from this one."""
planning = self.root / ".planning" / "2026-09-02-real"
planning.mkdir(parents=True)
(planning / "task_plan.md").write_text("# real\n", encoding="utf-8")
out = self._claude("post-tool-use", PLAN_ID="2026-09-02-ghost")
self.assertEqual("", out.strip())
if __name__ == "__main__":
unittest.main()