name: invoking-subagents description: Spawns subagents with configurable tool access that return just the answers without flooding your context. Use for summarizing extensive git history, comparing across multiple repositories in parallel, or processing large diffs/logs. compatibility: Requires synu shell plugin and claude CLI tool license: GPL-3.0-or-later metadata: author: Amolith amolith@secluded.site

Invoke with PI_PERMISSION_LEVEL=level pi -p 'prompt'. DO NOT impose a timeout. Set a different model, if requested, with pi --model "provider/model" -p "prompt".

Important: Subagents are scoped to their cwd. To invoke a subagent in another folder, cd there && PI_PERMISSION_LEVEL=level pi .... Subagents are also amnesic unless you follow up with -c. If you're coordinating between multiple subagents in the same directory, or there might be multiple working in the same directory that you're not controlling, -c might instead continue their conversation. In those cases, specify which pi --session <file> you want to continue.

Craft a precise and thorough prompt. Generally assume the model is intelligent and capable; don't prescribe too much of a process and instead prefer to give it all background, constraints, and goals. However, the user might compare the model to one of opus, sonnet, or haiku. If compared to sonnet, do prescribe a bit more process through leading, socratic questions. If compared to haiku, however, you ARE its planner and must prescribe the ENTIRE process. Haiku-equivalent models are fast, light, and cheap, but only effective if directed well. If directed poorly, they make a mess that's much harder to clean up.

You may invoke multiple subagents when appropriate and in parallel if helpful, using e.g. backgrounded commands or tmux. Once they're running, you may either stop and wait for me to tell you they're finished or continue with other work.

Aggressively restrict their permissions:

• minimal: read-only commands such as ls, cat, git status, etc.
• low: + write/edit files
• medium: + npm, git, make, cargo, etc.
• high: everything (though particular dangerous commands are still disallowed)

Example exploring git history in another repo:

cd /path/to/other/repo && PI_PERMISSION_LEVEL=minimal pi -p 'Using only git log and git show, summarise the major user-facing changes in HASH..HASH. Do not provide code snippets or technical details. Consider user-facing changes, like being able to set a port-out PIN or adding a new button or changing font sizes.'"