skills/planning-with-files
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
planning-with-files/scripts/skill-hook.sh
T

466 lines
17 KiB
Bash
Raw Permalink Blame History

#!/bin/sh
# Standalone Claude Code skill-hook entrypoint.
#
# Skill frontmatter command hooks receive their host identity as JSON on stdin;
# Claude Code does not export session_id for child processes. Keep stdin
# parsing here rather than teaching inject-plan.sh to consume input, because
# that script is also a public direct-call surface. UserPromptSubmit may emit
# plain context, while PreToolUse and PostToolUse require structured JSON for
# model-visible additionalContext.
#
# Events:
# userprompt re-arm this session's nudge, then preserve injector stdout.
# pretool serialize injector output as PreToolUse additionalContext.
# posttool validate the effective plan, then nudge once per turn.
# precompact forward the reminder with the resolved session identity.
# stop validate selection, then preserve stdin for the completion gate.
#
# The helper always exits 0. Missing identity or an unusable cache fails toward
# a repeated reminder, never toward a shared empty-id marker that could silence
# another session.
set -u
EVENT=""
for _arg in "$@"; do
case "$_arg" in
--event=*) EVENT="${_arg#--event=}" ;;
esac
done
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd 2>/dev/null)" || SCRIPT_DIR="."
INJECT_PLAN="${SCRIPT_DIR}/inject-plan.sh"
GATE_STOP="${SCRIPT_DIR}/gate-stop.sh"
CHECK_COMPLETE="${SCRIPT_DIR}/check-complete.sh"
FAST_PATH="${SCRIPT_DIR}/inject-plan.py"
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
[ -f "$INJECT_PLAN" ] || exit 0
# No planning state where the resolver will look and no selector to validate:
# every event below answers with nothing (and Stop is not consumed until a
# plan is accepted), so answer with nothing now, before any fork. A set
# PLAN_ID or PWF_PLAN_ROOT still gets its refusal notice from the injector.
if [ -z "${PLAN_ID:-}" ] && [ -z "${PWF_PLAN_ROOT:-}" ] \
&& [ ! -f task_plan.md ] && [ ! -d .planning ]; then
exit 0
fi
# Locate a CPython 3 without forking (v3.17.0). Every $(...) and every
# pipeline is a fork, and under Git Bash on Windows a fork costs about 90 ms;
# the old `$(command -v ...)` plus a `-c` version probe cost three of them on
# every event. This walk is stat calls only. Explicit PWF_TRUSTED_PYTHON or
# PYTHON_BIN wins; otherwise python3 is preferred over python across the whole
# PATH so an old distro's Python 2 `python` is never picked while a python3
# exists further down. Only absolute PATH entries are searched (a relative or
# empty entry would let the current repository plant the interpreter) and the
# Microsoft Store aliases are skipped by path: they are discoverable yet refuse
# to run a script. Python stays optional: without it the payload is still
# consumed to EOF, the session id is treated as absent, and the PostToolUse
# throttle deliberately degrades to repeat output.
select_python() {
for _fp_explicit in "${PWF_TRUSTED_PYTHON:-}" "${PYTHON_BIN:-}"; do
[ -n "$_fp_explicit" ] || continue
case "$_fp_explicit" in
/*|[A-Za-z]:[\\/]*) ;;
*) continue ;;
esac
case "$_fp_explicit" in
*[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]*) continue ;;
esac
if [ -f "$_fp_explicit" ] && [ -x "$_fp_explicit" ]; then
printf '%s\n' "$_fp_explicit"
return 0
fi
done
_fp_found=""
# set -u is active: an unset IFS or PATH must not kill the hook.
if [ "${IFS+set}" = set ]; then
_fp_saved_ifs="$IFS"
_fp_ifs_was_set=1
else
_fp_saved_ifs=""
_fp_ifs_was_set=0
fi
for _fp_name in python3 python; do
IFS=:
set -f
for _fp_dir in ${PATH-}; do
case "$_fp_dir" in
/*) ;;
*) continue ;;
esac
case "$_fp_dir" in
*[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]*) continue ;;
esac
if [ -f "${_fp_dir}/${_fp_name}" ] && [ -x "${_fp_dir}/${_fp_name}" ]; then
_fp_found="${_fp_dir}/${_fp_name}"
break
fi
done
set +f
if [ "$_fp_ifs_was_set" = 1 ]; then IFS="$_fp_saved_ifs"; else unset IFS; fi
if [ -n "$_fp_found" ]; then
printf '%s\n' "$_fp_found"
return 0
fi
done
return 1
}
PWF_PYTHON=""
select_python_into_var() {
# Assign without a subshell: the walk above is the only work this costs.
_spv_out="$(select_python 2>/dev/null)" || _spv_out=""
PWF_PYTHON="$_spv_out"
}
select_python_into_var
# Run the injector for one context. scripts/inject-plan.py is a byte-identical
# twin of inject-plan.sh in one interpreter process (about 130 forks fewer per
# event; see the header of hooks/claude-hook.sh). It exits 0 only when its
# stdout is the complete answer, so any other status falls back to the
# reference chain. PWF_FAST_PATH=0 forces the reference chain. -I keeps the
# project directory off sys.path; -B never writes bytecode into the skill dir.
# PWF_SHELL_PWD hands the twin this shell's $PWD spelling so both routes
# derive the same cache slots; MSYS2_ENV_CONV_EXCL keeps Git Bash from
# rewriting it on the way.
run_inject() {
if [ "${PWF_FAST_PATH:-}" != "0" ] && [ -n "$PWF_PYTHON" ] && [ -f "$FAST_PATH" ]; then
if PWF_SHELL_PWD="$PWD" \
MSYS2_ENV_CONV_EXCL="${MSYS2_ENV_CONV_EXCL:+${MSYS2_ENV_CONV_EXCL};}PWF_SHELL_PWD" \
"$PWF_PYTHON" -I -B "$FAST_PATH" "--context=$1" 2>/dev/null; then
return 0
fi
fi
sh "$INJECT_PLAN" "--context=$1" 2>/dev/null
}
# Keep the injector's established no-probe boundary. The preflight token is
# emitted only after a plan exists as a regular contained file, but before
# session admission needs stdin identity. Rejected paths must not make this
# wrapper execute any interpreter, so the preflight and the refusal notices
# stay on the shell chain; the twin runs only once the plan is accepted.
_preflight="$(sh "$INJECT_PLAN" --context=preflight 2>/dev/null)" || exit 0
if [ "$_preflight" != "PWF_PLAN_ELIGIBLE_V1" ]; then
case "$EVENT" in
userprompt) sh "$INJECT_PLAN" --context=userprompt 2>/dev/null || : ;;
precompact) sh "$INJECT_PLAN" --context=precompact 2>/dev/null || : ;;
esac
exit 0
fi
PARSED_IDENTITY=""
HOOK_PAYLOAD=""
if [ "$EVENT" = "stop" ]; then
# Stop's consumer must receive Claude's original JSON so stop_hook_active
# can prevent recursive continuation. Stop payloads are bounded host
# metadata; command substitution preserves the JSON while trimming only
# insignificant trailing newlines.
HOOK_PAYLOAD="$(cat 2>/dev/null)" || HOOK_PAYLOAD=""
fi
parse_identity() {
"$PWF_PYTHON" -I -c '
import hashlib
import json
import re
import sys
SAFE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,127}\Z")
try:
payload = json.load(sys.stdin)
except (json.JSONDecodeError, OSError, UnicodeError, ValueError):
raise SystemExit(0)
if not isinstance(payload, dict):
raise SystemExit(0)
session_id = payload.get("session_id")
if not isinstance(session_id, str) or SAFE.fullmatch(session_id) is None:
raise SystemExit(0)
agent_id = payload.get("agent_id")
prompt_id = payload.get("prompt_id")
agent_valid = agent_id is None or (
isinstance(agent_id, str) and SAFE.fullmatch(agent_id) is not None
)
prompt_valid = isinstance(prompt_id, str) and SAFE.fullmatch(prompt_id) is not None
marker_key = ""
if agent_valid and (agent_id is None or prompt_valid):
digest = hashlib.sha256(b"planning-with-files-skill-turn-v1\0")
for value in (session_id, agent_id or "main"):
encoded = value.encode("utf-8", "surrogatepass")
digest.update(len(encoded).to_bytes(8, "big"))
digest.update(encoded)
marker_key = digest.hexdigest()
print("|".join((session_id, marker_key, prompt_id if prompt_valid else "")))
' 2>/dev/null
}
if [ -n "$PWF_PYTHON" ]; then
# Output is delimiter-safe because every source field is allowlisted. The
# marker key includes agent_id when present, so sibling agents in one Claude
# session cannot suppress one another. Old hosts without prompt_id still
# use UserPromptSubmit re-arming for the main agent; subagents without a
# turn id skip throttling rather than risk a permanent marker.
if [ "$EVENT" = "stop" ]; then
PARSED_IDENTITY="$(printf '%s' "$HOOK_PAYLOAD" | parse_identity)" \
|| PARSED_IDENTITY=""
else
PARSED_IDENTITY="$(parse_identity)" || PARSED_IDENTITY=""
fi
else
# The host writes one complete JSON payload. Consume it even on the
# dependency-free fallback so the hook owns exactly one native stdin frame.
[ "$EVENT" = "stop" ] || cat >/dev/null 2>&1 || :
fi
# Never trust a manually inherited PWF_SESSION_ID over the hook's own payload.
unset PWF_SESSION_ID
SESSION_ID=""
TURN_KEY=""
PROMPT_ID=""
case "$PARSED_IDENTITY" in
*"|"*"|"*)
SESSION_ID="${PARSED_IDENTITY%%|*}"
_identity_tail="${PARSED_IDENTITY#*|}"
TURN_KEY="${_identity_tail%%|*}"
PROMPT_ID="${_identity_tail#*|}"
PWF_SESSION_ID="$SESSION_ID"
export PWF_SESSION_ID
;;
esac
turn_cache_root() {
if [ -n "${XDG_CACHE_HOME:-}" ]; then
printf '%s\n' "${XDG_CACHE_HOME}/pwf-turn"
elif [ -n "${HOME:-}" ]; then
printf '%s\n' "${HOME}/.cache/pwf-turn"
else
return 1
fi
}
clear_turn_marker() {
[ -n "$TURN_KEY" ] || return 0
_root="$(turn_cache_root 2>/dev/null)" || return 0
cache_action clear "$_root" >/dev/null 2>&1 || :
}
# Cache state is advisory, but it still must not follow a planted link or use a
# directory controlled by another account. TURN_KEY exists only when the
# already-selected Python parsed an authentic bounded identity, so use that
# interpreter for lstat/ownership/mode checks before and after directory setup.
cache_action() {
_cache_action="$1"
_cache_root="$2"
"$PWF_PYTHON" -I - "$_cache_action" "$_cache_root" "$TURN_KEY" "$PROMPT_ID" <<'PY'
import os
import secrets
import stat
import sys
action, root, key, prompt_id = sys.argv[1:]
reparse = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
no_follow = getattr(os, "O_NOFOLLOW", 0)
binary = getattr(os, "O_BINARY", 0)
def identity(info):
return info.st_dev, info.st_ino, info.st_mode
def same_object(left, right):
return (left.st_dev, left.st_ino) == (right.st_dev, right.st_ino)
def acceptable_directory(info):
if not stat.S_ISDIR(info.st_mode):
return False
if getattr(info, "st_file_attributes", 0) & reparse:
return False
return os.name != "posix" or info.st_uid == os.getuid()
def acceptable_file(info):
if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1 or info.st_size > 256:
return False
if getattr(info, "st_file_attributes", 0) & reparse:
return False
return os.name != "posix" or info.st_uid == os.getuid()
temporary = ""
try:
if not key or len(key) != 64 or any(char not in "0123456789abcdef" for char in key):
raise OSError("invalid cache key")
existed = os.path.lexists(root)
if existed and not acceptable_directory(os.lstat(root)):
raise OSError("unsafe cache root")
os.makedirs(root, mode=0o700, exist_ok=True)
before = os.lstat(root)
if not acceptable_directory(before):
raise OSError("unsafe cache root")
if os.name == "posix":
os.chmod(root, 0o700)
after = os.lstat(root)
# chmod intentionally changes st_mode. Freeze the directory object across
# that operation, then use the post-chmod identity for every later check.
if not acceptable_directory(after) or not same_object(before, after):
raise OSError("cache root changed")
if os.name == "posix" and stat.S_IMODE(after.st_mode) & 0o077:
raise OSError("cache root is not private")
root_real = os.path.realpath(os.path.abspath(root))
slot = os.path.join(root_real, key)
if os.path.commonpath((root_real, slot)) != root_real:
raise OSError("cache slot escaped")
if action == "clear":
if not os.path.lexists(slot):
raise SystemExit(0)
slot_info = os.lstat(slot)
if not acceptable_file(slot_info):
raise OSError("unsafe cache slot")
os.unlink(slot)
raise SystemExit(0)
if action != "claim":
raise OSError("unknown cache action")
desired = ((prompt_id or "legacy") + "\n").encode("ascii", "strict")
if os.path.lexists(slot):
slot_before = os.lstat(slot)
if not acceptable_file(slot_before):
raise OSError("unsafe cache slot")
descriptor = os.open(slot, os.O_RDONLY | binary | no_follow)
try:
opened = os.fstat(descriptor)
slot_after = os.lstat(slot)
if (
not acceptable_file(opened)
or identity(slot_before) != identity(opened)
or identity(slot_after) != identity(opened)
):
raise OSError("cache slot changed")
previous = os.read(descriptor, 257)
finally:
os.close(descriptor)
if previous == desired:
print("seen")
raise SystemExit(0)
temporary = os.path.join(root_real, f".{key}.{os.getpid()}.{secrets.token_hex(8)}")
descriptor = os.open(
temporary,
os.O_CREAT | os.O_EXCL | os.O_WRONLY | binary | no_follow,
0o600,
)
try:
os.write(descriptor, desired)
finally:
os.close(descriptor)
root_final = os.lstat(root)
if not acceptable_directory(root_final) or identity(after) != identity(root_final):
raise OSError("cache root changed")
os.replace(temporary, slot)
temporary = ""
claimed = os.lstat(slot)
if not acceptable_file(claimed) or claimed.st_size != len(desired):
raise OSError("unsafe claimed slot")
print("claimed")
except (OSError, UnicodeError, ValueError):
pass
finally:
if temporary:
try:
os.unlink(temporary)
except OSError:
pass
PY
}
# Return 0 when the reminder should be emitted, 1 when this turn already saw
# it. Any unsafe or unusable cache result fails toward the reminder.
claim_turn_marker() {
[ -n "$TURN_KEY" ] && [ -n "$PWF_PYTHON" ] || return 0
_root="$(turn_cache_root 2>/dev/null)" || return 0
_cache_result="$(cache_action claim "$_root" 2>/dev/null)" || _cache_result=""
[ "$_cache_result" = "seen" ] && return 1
return 0
}
# Encode the injector's bounded output without interpolating it into a command
# or format string. Walk characters directly because awk implementations do
# not agree on how many escapes gsub replacement text consumes. LC_ALL=C
# makes the walk byte-wise: in a UTF-8 locale gawk on Windows walks UTF-16
# units and re-emits a character outside the BMP as a lone surrogate.
json_string() {
tr '\001-\011\013-\037' ' ' \
| LC_ALL=C awk 'BEGIN { first = 1 }
{
if (!first) printf "\\n"
for (i = 1; i <= length($0); i++) {
c = substr($0, i, 1)
if (c == "\\") printf "%s", "\\\\"
else if (c == "\"") printf "%s", "\\\""
else printf "%s", c
}
first = 0
}'
}
emit_context_json() {
_event_name="$1"
_context="$2"
[ -n "$_context" ] || return 0
_encoded="$(printf '%s' "$_context" | json_string)"
printf '{"hookSpecificOutput":{"hookEventName":"%s","additionalContext":"%s"}}\n' \
"$_event_name" "$_encoded"
}
case "$EVENT" in
userprompt)
clear_turn_marker
[ -f "$INJECT_PLAN" ] || exit 0
# Plain stdout is explicitly model context for UserPromptSubmit. Do
# not capture or reframe it: preserve injector output byte-for-byte.
run_inject userprompt || :
;;
pretool)
_context="$(run_inject pretool)" || exit 0
emit_context_json "PreToolUse" "$_context"
;;
posttool)
[ -f "$INJECT_PLAN" ] || exit 0
_decision="$(run_inject validate)" || exit 0
[ "$_decision" = "PWF_PLAN_ACCEPTED_V1" ] || exit 0
claim_turn_marker || exit 0
printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"[planning-with-files] Update progress.md with what you just did. If a phase is now complete, update task_plan.md status."}}'
;;
precompact)
# PreCompact does not support additionalContext. Preserve the current
# plain diagnostic output and pass only the real session identity into
# resolution; do not invent an unsupported event-specific JSON field.
run_inject precompact || :
;;
stop)
_decision="$(run_inject validate)" || exit 0
[ "$_decision" = "PWF_PLAN_ACCEPTED_V1" ] || exit 0
if [ -f "$GATE_STOP" ]; then
printf '%s' "$HOOK_PAYLOAD" | sh "$GATE_STOP" 2>/dev/null || :
elif [ -f "$CHECK_COMPLETE" ]; then
# Some existing IDE mirrors ship check-complete.sh without the thin
# gate-stop.sh dispatcher. Keep their current Stop capability.
printf '%s' "$HOOK_PAYLOAD" | sh "$CHECK_COMPLETE" --gate 2>/dev/null || :
fi
;;
*)
exit 0
;;
esac
exit 0
Reference in New Issue View Git Blame Copy Permalink