# Saved agent reports and cleanup For users retrieving completed work or reclaiming disk space. This guide covers saved results and generated artifacts, not agent definitions or project source. ## Find completed work `get_subagent_result` checks live work first, then retained reports. Completed reports and their available metadata are retained for **30 days from completion**, independently of the roughly ten-minute in-memory worker cleanup. Reloading or restarting pi does not discard a persisted report within that window. ```text get_subagent_result({ agent_id: "" }) get_subagent_result({ agent_id: "", verbose: true }) ``` Use the exact ID for work from another session or project. A handle or alias searches the current root session only; it is not a global search for whichever similarly named agent finished most recently. A live or resumed run takes precedence over its earlier saved answer. Nested callers can retrieve only their own children; the archive does not make another parent's children or workflow-owned agents public. The final report is stored and returned whole, without a character cap or a summarizer. Saved metadata can include status, timestamps, model/invocation information, tool counts, usage and artifact paths. Older recovered reports may lack some fields; missing information is not invented. Non-normal outcomes remain labelled partial, stopped, errored or wrapped up rather than being presented as successful completion. A saved read does not trigger another completion notification or charge its recorded usage again. It does not resume the worker. The Agent Hub remains the live/runtime roster; this feature does not load every historical session into memory or add an archive browser. ### Raw details are opt-in `verbose: true` can include the existing conversation/transcript when it is still available. A normal read does not inject raw tool logs or a conversation into the main model's context. No second durable copy of every raw transcript is created just to retain the final report. Raw files retain their existing lifetimes: temporary `.output` files can disappear during an OS temp sweep or reboot, and `persist_session` / `output_transcript` settings still apply. A missing raw file does not remove the separate saved final report. An explicitly ephemeral main session does not gain persistent report copies; memory/current-parent history is available only while that session survives. ### Older work For pre-upgrade agents, surviving parent-session `subagents:record` entries and known task transcripts can help recover the original report. Cross-session recovery verifies the matching parent session and top-level record rather than inferring a successful run from an assistant's `stop` reason. The exact saved terminal status is authoritative. This is best-effort migration, not reconstruction: already-deleted data cannot be recreated, and unverified ownership is not guessed. A deliberately deleted or expired report is not silently re-imported from an old transcript or parent record. No prefix guessing is used; this extension's normal IDs are already shortened canonical IDs. ## Storage and expiry Reports live under: ```text /pi-subagents/reports// ``` `` follows `PI_CODING_AGENT_DIR` (normally `~/.pi/agent`). Report files contain plain data, not live SDK sessions, controllers or promises. Shutdown waits for pending root bindings before flushing and closing their stores. Private permissions are used where supported. Short ownership/lease files coordinate cleanup across updated pi instances. Expiry is measured from the report's original completion time, not from its recovery/import time. Startup/save maintenance expires report bodies after 30 days; reads do not delete files. Minimal artifact-ownership information may remain so later cleanup can safely remove associated generated files. A small main-session identity record is also kept where needed to prevent later cleanup from mistaking a main pi conversation for deletable child history; it contains no report body. Explicit cleanup may retain a small deletion receipt for up to 30 days to prevent old copies being automatically rediscovered. ## Preview cleanup ```text /subagents cleanup session --dry-run /subagents cleanup global --dry-run ``` | Scope | Meaning | |---|---| | `session` (default) | Eligible completed work from the current root session | | `global` | Eligible generated work across all projects and sessions | The preview lists exact eligible paths, file counts/bytes, and skipped/protected items with reasons. It does not delete or modify the target data. Global is not a synonym for every session in the current project. ## Confirm deletion ```text /subagents cleanup /subagents cleanup session /subagents cleanup global ``` Normal cleanup previews the candidate list and then requires explicit confirmation in the native terminal UI. RPC/print contexts cannot approve deletion. Cancelling, invalid arguments, or a context without confirmation UI deletes nothing. There is no `--yes` bypass. Cleanup includes saved reports, generated task transcripts, generated temporary workflow scripts/journals and child-session history only when its ownership can be proved. Saved/external workflow sources are not generated copies and are never removed. A workflow with zero agents still has its generated artifacts registered. **Unread work is not silently discarded.** The preview labels unread artifact files and unrecorded archive read state as unknown; confirmation separately counts distinct pending live results. Confirming deletion deliberately discards the selected reports and their unsent pending delivery. Surviving group members keep their notifications. Messages already sent to pi and copies already embedded in main conversation history cannot be withdrawn by this command. ### Protected and skipped data Cleanup never removes project source, agent definitions, settings, memory, saved workflows, schedule definitions, main pi conversation files, git branches or git worktrees. In particular, it is not a way to erase report copies embedded in your main pi history. Running, queued and still-settling work is protected, along with active workflow/owner dependencies and history files shared with active resumes. Other updated active instances hold leases. A root with active or uncertain work is left alone, even if some of its reports have finished; global cleanup can still process other idle roots. Data whose teardown timed out or failed remains protected rather than being assumed idle. Every file is rechecked after confirmation. Live work, owner dependencies and protected paths are refreshed immediately before each removal or deletion-receipt publication, including publication retries. Changed generations/files, symlinks/junction escapes, unexpected ownership and contention are skipped. Cleanup removes only previewed files, never force-removes a tree. Empty managed directories can be removed only when empty. A partial failure reports what was deleted and what remains; it does not claim the whole scope was cleaned. ### Legacy artifacts Older instances have no activity leases or modern child-history ownership markers. Update/reload or close other instances before broad cleanup. To include supported, validated legacy generated files: ```text /subagents cleanup global --include-legacy --dry-run /subagents cleanup global --include-legacy ``` The deleting form requires an additional confirmation that older unleased instances are closed. This is not a force flag: malformed/unproven files and unmarked pi session histories still remain untouched and are reported as skipped. Preview the list instead of assuming every old folder is disposable. ## Existing model toggle `/subagents`, `/subagents on` and `/subagents off` retain their existing main-model-twin toggle behavior. Cleanup is a separate subcommand; a typo in its arguments does not toggle agent model selection.