Follow up Pi Coding Agent upstream updates: stop hook should map to agent_settled, AGENTS.override.md not emittable

[dyoshikawa]

Summary

Two Pi Coding Agent drifts as of v0.84.0 (2026-08-06): the canonical stop hook is mapped to agent_end, which upstream now documents as the wrong analogue (it fires per low-level run, including auto-retries and queued follow-ups — agent_settled is the "agent actually finished" event); and the new v0.84.0 AGENTS.override.md per-directory context override cannot be emitted.

Recent Releases

• v0.84.0 (2026-08-06) — https://github.com/earendil-works/pi/releases — adds AGENTS.override.md (PR #7681).
• agent_settled lifecycle event introduced 2026-07-09 (commit "fix(coding-agent): add settled agent lifecycle event"), postdating rulesync's current mapping.

Gaps

1. hooks — canonical stop maps to agent_end instead of agent_settled

• Upstream (extensions.md at v0.84.0): "agent_end fires when that run ends, but Pi may still auto-retry, auto-compact and retry, or continue with queued follow-up messages. Use agent_settled for status integrations that need to know Pi will not continue running automatically." The lifecycle diagram shows agent_settled after agent_end, annotated "(no retry/compaction/follow-up left)".
• rulesync (project, global): CANONICAL_TO_PI_EVENT_NAMES maps stop: "agent_end" (src/types/hooks.ts:1169); agent_settled appears nowhere in src/. A user's stop hook (e.g. a notification ported from Claude Code) fires several times for a single user turn.
• Follow-up: remap stop → "agent_settled" with a comment recording why agent_end is wrong; update pi-hooks.test.ts and the hooks reference docs. PI_HOOK_EVENTS itself is unchanged.

2. rules — AGENTS.override.md not emittable

• Upstream (usage.md at v0.84.0, Context Files): "If a directory contains AGENTS.override.md, Pi loads it instead of AGENTS.md or CLAUDE.md from that directory."
• rulesync: pi-rule.ts emits only the root AGENTS.md plus the opt-in .pi/APPEND_SYSTEM.md. Where a rulesync-generated AGENTS.md and a hand-authored CLAUDE.md coexist, the docs state no precedence — AGENTS.override.md is the upstream mechanism to make rulesync-managed context deterministically win, and rulesync cannot produce it.
• Follow-up: a pi.contextFile: "override" frontmatter opt-in on the root rule switching the emitted filename, wired through getSettablePaths, fromFile, forDeletion, and import so a stale AGENTS.md is cleaned up when flipped.

Verified in parity

mcp / subagents / permissions / ignore are intentionally absent upstream ("No MCP. Build CLI tools with READMEs, or build an extension"); the only tool gate is blocking inside tool_call, already reachable via preToolUse. Commands carry both documented fields; skills cover the full SKILL.md spec; the other ten mapped hook event names all exist verbatim in v0.84.0.

References

• https://github.com/earendil-works/pi/blob/v0.84.0/packages/coding-agent/docs/extensions.md — agent_end vs agent_settled
• https://github.com/earendil-works/pi/blob/v0.84.0/packages/coding-agent/docs/usage.md — AGENTS.override.md
• https://github.com/earendil-works/pi/releases — v0.84.0 dating

[dyoshikawa]

Closed by #2627.

Gap 2 is implemented: a root: true rule can set pi.contextFile: override to emit the root context file as AGENTS.override.md. Verified against the upstream loader before implementing — loadContextFileFromDir in packages/coding-agent/src/core/resource-loader.ts tries AGENTS.override.md first and loadProjectContextFiles applies it to the global agent dir as well, so the override wins deterministically at both scopes. Because Pi folds every rule body into one root file, an opted-in root rule decides for all Pi rules; setting it only on a non-root rule is ignored with a warning. The project-root AGENTS.md is never deleted on Pi's behalf (other targets write that path).

Gap 1 is closed as intended behavior, not a bug. The stop → agent_end mapping was made on 2026-07-19, ten days after agent_settled and its recommendation text already existed upstream (commit e9fa5a68, 2026-07-09), so it was not made in ignorance of the alternative — and src/types/hooks.ts:1146-1152 records it as a deliberate trade-off: agent_settled would skip queued follow-ups instead, which is a trade-off rather than a strict improvement, so it is intentionally unmapped. Revisiting it would be a canonical-semantics design decision worth its own issue.