Tear down configure_my_pi_setup after the setup episode #16

Parent

#15 — Hide configure_my_pi_setup until /openpi-setup. That ticket makes the tool default-hidden and exposes it for the rest of the session after the first command. This ticket closes the window when the setup episode ends.

Problem

/openpi-setup is not an object that owns a conversation. The command handler injects a user message and returns. Persist happens later, inside the model loop, when configure_my_pi_setup runs. The interactive prompt also allows “keep current settings → do not call the tool.”

So “successful apply” has a tool_execution_end to hang teardown on. “Keep, do not apply” does not. If we hide too early, the next turn cannot persist and usage breaks. If we hide too late, the same session keeps paying the 6,351-character tax after the user is already back to coding.

Pi 0.84.1 cannot unregisterTool. Teardown is getActiveTools() minus configure_my_pi_setup, then setActiveTools. That replacement is the whole active list; do not snapshot-and-blindly-restore across reload or other callers. Changes take effect on the next agent turn.

How to change it

Define the episode as the one agent run that consumes the injected setup user message, including in-loop ask_user. That matches the current prompt contract (“use ask_user, do not only print questions”). Do not add a product state machine for multi-turn plain-text Q&A — that path already violates the prompt.

Hide when either:

1. the typed tool applies successfully, or
2. that agent run settles without a still-pending setup persist.

Then:

• Re-entry: a later /openpi-setup must get+add the name again. Re-register is not enough.
• session_start / /reload: if no episode is armed, hide. Host reconstructs with includeAllExtensionTools: true.
• In-flight /openpi-setup while a turn is busy already uses deliverAs: "followUp". Do not treat “the next agent_settled” as episode end if that settled run is the current turn and the setup message has not been consumed yet.
• Plan mode already blocks this tool. Exposing it during /plan makes a visible dead tool; do not special-case a new setup UX. Existing gate stays.

Update the package contract in the same change: natural language is still interpreted by the model during an /openpi-setup episode; the configuration tool is not a resident model-facing tool. Touch AGENTS.md, no-arg /openpi-setup status wording if it implies a always-present tool, SETUP.md, README.md (defaults table / tool list), child-session classification (keep excluded), and plan-mode’s known-mutation list (keep blocked if the name still exists).

Why this way

Ticket #15 already removes the tax from sessions that never configure. This ticket removes it from the rest of a session after the user has configured. The alternative — leave it active until process exit — is the documented fallback only if hide-after-episode cannot be made correct. It is not the goal.

“Fail closed” is two opposite things: default hidden, versus “when unsure whether the episode ended, persist must still work.” Prefer a slightly longer window over a broken write. Never fail into “permanently resident for all future sessions.”

Value

• After /openpi-setup finishes, ordinary coding turns in that same session no longer carry the config schema.
• Contract and docs stop describing a resident configure_my_pi_setup.
• Still no new feature, no second entry point, no parser.

Out of scope

• Host-only native setup form.
• Discoverable Skill.md.
• Compressing workflow / ask_user.
• New episode UX for models that ignore ask_user and ask in prose.

Acceptance criteria

• After a successful configure_my_pi_setup, the next agent turn does not see the tool unless the user ran /openpi-setup again.
• After a keep-current-settings episode (no tool call), the next non-setup turn does not see the tool.
• A follow-up /openpi-setup delivered onto a busy turn still sees the tool on the setup turn (do not tear down the in-flight run).
• A second /openpi-setup after teardown can persist again (get+add).
• /reload / new session_start without an armed episode starts hidden.
• AGENTS.md, SETUP.md, and README.md state that the write tool is episode-scoped, not resident. Child-session and plan-mode still deny it.
• Tests cover apply teardown, keep-without-apply teardown, follow-up-while-busy, re-entry, and reload. Do not snapshot-restore the entire active tool list.
• Format, lint, typecheck, and the full test suite pass.

Blocked by

• Hide configure_my_pi_setup until /openpi-setup #15