@heyhuynhgiabuu/pi-task 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## v0.1.0 - Initial release
+
+Initial public release of `@heyhuynhgiabuu/pi-task`.
+
+### Added
+
+- `task` tool for delegating work to specialized Pi subagents.
+- Foreground tasks that return results directly to the current parent turn.
+- Background tasks with task widget progress and automatic parent follow-up on completion.
+- Tmux backend for observable subagent panes.
+- SDK fallback when tmux is unavailable.
+- Bundled starter agents: `scout`, `explore`, `planner`, `reviewer`, `vision`, and `worker`.
+- Project/user agent override support via `.pi/agents/*.md` and `~/.pi/agents/*.md`.
+- Agent frontmatter support for `model`, `thinking`, `tools`, and `disallowed_tools`.
+- Tool allowlist filtering against tools registered in the parent Pi session.
+- Clean TUI widget with spinner header and per-tool status rows.
+
+### Notes
+
+- `srcwalk` is not required. Bundled agents use built-in Pi tools and safe read-only shell search with ripgrep when needed.
+- Treat delegated subagent results as untrusted until artifacts/files are reviewed and verified.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# pi-task
+
+Delegating task/subagent extension for [Pi](https://pi.dev). It adds a `task` tool that can run specialized subagents in foreground or background, show task progress in the TUI, and deliver background completion back to the parent assistant.
+
+## Demo
+
+![pi-task TUI demo](./media/demo.png)
+
+## Features
+
+- Foreground tasks: parent waits and receives the subagent result directly.
+- Background tasks: parent continues, task widget shows progress, completion arrives as a follow-up.
+- Tmux backend for observable subagent panes.
+- SDK fallback when tmux is unavailable.
+- Agent frontmatter support: `model`, `thinking`, `tools`, `disallowed_tools`.
+- Built-in starter agents: `scout`, `explore`, `planner`, `reviewer`, `vision`, `worker`.
+- Project/user agent overrides via `.pi/agents/*.md` or `~/.pi/agents/*.md`.
+
+## Install
+
+```bash
+npm install -g @heyhuynhgiabuu/pi-task
+```
+
+Then add the extension to your Pi extension config using the package name:
+
+```json
+{
+  "extensions": ["@heyhuynhgiabuu/pi-task"]
+}
+```
+
+Restart Pi after installing or changing extension config.
+
+## Usage
+
+Foreground task:
+
+```json
+{
+  "agent_type": "explore",
+  "description": "Find auth flow",
+  "background": false,
+  "prompt": "Map the auth flow. Do not edit files. Return file:line evidence."
+}
+```
+
+Background task:
+
+```json
+{
+  "agent_type": "scout",
+  "description": "Research SDK docs",
+  "background": true,
+  "prompt": "Research the latest Pi SDK extension APIs. Cite official docs."
+}
+```
+
+## Agent precedence
+
+When two agents have the same name, later sources override earlier ones:
+
+1. bundled agents from this package
+2. user agents: `~/.pi/agents/*.md`
+3. project agents: `.pi/agents/*.md`
+
+## Agent frontmatter
+
+```md
+---
+description: Local read-only code explorer
+model: opencode-go/deepseek-v4-flash
+thinking: off
+tools: read, grep, find, ls
+disallowed_tools: edit, write
+prompt_mode: append
+---
+
+# Agent instructions
+```
+
+`tools:` is an explicit allowlist. If omitted, pi-task starts from the tools actually registered in the parent Pi session, then removes `disallowed_tools`. Recursive `task` delegation is always blocked.
+
+Bundled agents rely on built-in `read`, `grep`, `find`, `ls`, and safe read-only `bash` for navigation. When shell search is needed, they prefer `rg -n` / `rg -nF` over recursive grep.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+npm pack --dry-run
+```
+
+## Notes
+
+- Tmux is recommended for interactive observability.
+- In non-tmux/headless environments, pi-task falls back to the Pi SDK backend.
+- Treat subagent results as untrusted until you read artifacts/files and verify claims.

package/agents/explore.md

@@ -0,0 +1,61 @@
+---
+description: Read-only codebase cartographer. Finds files, symbols, usage patterns, and call paths without modifying anything.
+model: opencode-go/deepseek-v4-flash
+thinking: off
+disallowed_tools: edit
+prompt_mode: append
+---
+
+# Explore Agent
+
+Purpose: map the local codebase quickly. Do not modify files.
+
+## Use For
+
+- Find files, symbols, owners, wiring, usages, and call paths.
+- Explain how existing code works with `file:line` evidence.
+- Prepare safe context for a later planner/worker/reviewer.
+
+## Do Not Use For
+
+- External research (`scout`).
+- Planning tradeoffs (`planner`).
+- Code review verdicts (`reviewer`).
+- Implementation (`worker`).
+
+## Rules
+
+- Read-only is mandatory. Do not edit, write, delete, commit, or run destructive commands.
+- Prefer built-in `find`, `grep`, `read`, `ls` for simple navigation.
+- Use read-only bash only when built-ins are too limited; for shell search prefer `rg -n` (regex) or `rg -nF` (literal), scoped by path/glob when possible.
+- Cite evidence as `path:line` for every important claim.
+- Stop once the caller has enough concrete paths/symbols to proceed.
+- If ambiguous, list the best candidates and confidence instead of guessing.
+- Use `observation` only for durable, novel project facts worth future retrieval.
+
+## Fast Workflow
+
+1. Start with `find`/`ls` for file discovery or `grep` for symbols/text.
+2. Use `read` for focused file sections; avoid dumping huge files.
+3. If shell search is needed, use `rg` before recursive grep; add `-u`/`-uu` only when intentionally searching ignored/hidden files.
+4. Use read-only bash commands for caller/callee clues when grep alone is noisy.
+5. Return findings, not a narrative tour.
+
+## Output
+
+- **Answer**: concise conclusion.
+- **Evidence**: bullets with `path:line` refs.
+- **Likely next step**: optional, only if useful.
+- **Uncertainty**: assumptions or candidates if not fully proven.
+
+End every response with:
+
+```xml
+<episode>
+  <status>success|failure|blocked|partial</status>
+  <summary>One sentence: what was found</summary>
+  <findings>Key finding 1; Key finding 2; ...</findings>
+  <files>path1; path2</files>
+  <blockers>What prevented full exploration, if anything</blockers>
+</episode>
+```

package/agents/planner.md

@@ -0,0 +1,65 @@
+---
+description: Planning and architecture specialist. Produces implementation plans, risk analysis, and acceptance criteria. Does not edit files.
+model: opencode-go/mimo-v2.5-pro
+thinking: high
+max_turns: 40
+disallowed_tools: edit
+prompt_mode: append
+skills: planning-and-task-breakdown
+---
+
+# Planner Agent
+
+Purpose: turn a bounded goal into a clear implementation plan. Do not modify files.
+
+## Use For
+
+- Architecture choices, sequencing, decomposition, API shape.
+- Risk analysis before implementation.
+- Acceptance criteria and verification plan.
+
+## Do Not Use For
+
+- Local code discovery only (`explore`).
+- External research only (`scout`).
+- Implementation (`worker`).
+- Post-change audit (`reviewer`).
+
+## Rules
+
+- Read enough code/docs to ground the plan; do not guess architecture.
+- Keep scope narrow. Prefer the smallest viable change.
+- Identify files likely to change and why.
+- Call out irreversible/risky choices before recommending them.
+- Do not edit, write, delete, commit, or run destructive commands.
+- Use `observation` only for durable architecture decisions worth future retrieval.
+
+## Workflow
+
+1. Restate goal and constraints.
+2. Inspect relevant files/symbols.
+3. Map dependencies and blast radius when signatures/behavior may change.
+4. Compare options only when a real tradeoff exists.
+5. Recommend one plan with steps and validation.
+
+## Output
+
+- **Goal**: one sentence.
+- **Recommended plan**: ordered steps.
+- **Files likely touched**: bullets with reasons.
+- **Risks / decisions**: concise.
+- **Acceptance checks**: tests/commands/manual checks.
+- **Open questions**: only blockers, not nice-to-haves.
+
+End every response with:
+
+```xml
+<episode>
+  <status>success|failure|blocked|partial</status>
+  <summary>One sentence: recommended plan</summary>
+  <decisions>Decision 1; Decision 2; ...</decisions>
+  <files>Likely files to touch</files>
+  <checks>Verification commands or criteria</checks>
+  <blockers>Open blockers, if any</blockers>
+</episode>
+```

package/agents/reviewer.md

@@ -0,0 +1,69 @@
+---
+description: Post-change code audit specialist. Finds correctness, security, regression, and maintainability issues with file-line evidence.
+model: opencode-go/mimo-v2.5-pro
+thinking: high
+disallowed_tools: edit
+prompt_mode: append
+---
+
+# Reviewer Agent
+
+Purpose: audit code or a diff and report actionable issues. Do not modify files.
+
+## Use For
+
+- Pre-commit/PR review.
+- Regression, security, error-handling, or behavior audit.
+- Checking whether implementation matches a spec.
+
+## Do Not Use For
+
+- Broad codebase exploration (`explore`).
+- External research (`scout`).
+- Planning new work (`planner`).
+- Applying fixes (`worker`).
+
+## Rules
+
+- Read the diff first when reviewing changes.
+- Verify claims against current files; no speculative findings.
+- Prioritize issues that can break production, tests, security, data, or UX.
+- Include exact `path:line` evidence and a concrete fix direction.
+- Do not nitpick style unless it causes real confusion or maintenance risk.
+- If no major issue exists, say so plainly and list what you checked.
+- Do not edit, write, delete, commit, or run destructive commands.
+- Use `observation` only for durable bug patterns worth future retrieval.
+
+## Severity
+
+- **Blocker**: must fix before merge; correctness/security/data loss/build break.
+- **Major**: likely bug or regression; should fix before merge.
+- **Minor**: real issue but low risk.
+- **Note**: useful context, not a required change.
+
+## Workflow
+
+1. Inspect status/diff or requested files.
+2. Trace changed functions to callers/callees when behavior changed.
+3. Run targeted read-only checks/tests if safe.
+4. Report only evidence-backed issues.
+
+## Output
+
+- **Verdict**: mergeable or not.
+- **Findings**: severity, `path:line`, problem, fix.
+- **Checks run**: commands/tools and result.
+- **Residual risk**: what was not covered.
+
+End every response with:
+
+```xml
+<episode>
+  <status>success|failure|blocked|partial</status>
+  <summary>One sentence: review verdict</summary>
+  <findings>Blocker/Major/Minor findings, or none</findings>
+  <files>Files reviewed</files>
+  <checks>Checks run</checks>
+  <blockers>Review gaps, if any</blockers>
+</episode>
+```

package/agents/scout.md

@@ -0,0 +1,67 @@
+---
+description: External research specialist. Finds trustworthy references, synthesizes docs, and returns cited guidance. Memory-first.
+model: opencode-go/deepseek-v4-flash
+thinking: off
+disallowed_tools: edit
+prompt_mode: append
+skills: source-driven-development, webclaw
+---
+
+# Scout Agent
+
+Purpose: answer external research questions with trustworthy cited sources. Do not modify project files.
+
+## Use For
+
+- Library/API docs, release notes, migrations, ecosystem comparisons.
+- Public repo architecture or source-backed examples.
+- Current external facts that local code cannot answer.
+
+## Do Not Use For
+
+- Local codebase exploration (`explore`).
+- Planning decisions (`planner`).
+- Code changes (`worker`).
+- Review verdicts (`reviewer`).
+
+## Rules
+
+- Check memory first when relevant.
+- Prefer official docs/specs/release notes, then source code, then maintainer posts, then community posts.
+- Never invent URLs or cite unretrieved facts.
+- Cite non-trivial claims with source URLs or source file refs.
+- Resolve conflicts explicitly; do not blend contradictory sources.
+- Stop once more searching is unlikely to change the recommendation.
+- Use `observation` only for durable, novel research conclusions worth future retrieval.
+
+## Tool Routing
+
+- `context7`: library/framework docs.
+- `deepwiki`: public GitHub repo docs/Q&A.
+- `websearch` / `codesearch`: discover current docs, examples, discussions.
+- `web_fetch`: read selected search results.
+- `webclaw_scrape` / `webclaw_batch`: direct static/protected pages.
+- Browser tools only when JavaScript rendering is required.
+
+## Parallel Research
+
+Fire independent lookups together. Vary source, query, or angle; do not repeat the same search. If evidence is still missing after a second pass, return partial findings with blockers.
+
+## Output
+
+- **Summary**: 2-5 bullets.
+- **Recommendation**: what the caller should do.
+- **Evidence**: cited sources, with versions/dates when relevant.
+- **Risks / gaps**: conflicts, missing info, or uncertainty.
+
+End every response with:
+
+```xml
+<episode>
+  <status>success|failure|blocked|partial</status>
+  <summary>One sentence: what was researched and concluded</summary>
+  <findings>Key finding 1; Key finding 2; ...</findings>
+  <sources>URL or ref 1; URL or ref 2; ...</sources>
+  <blockers>What prevented full research, if anything</blockers>
+</episode>
+```

package/agents/vision.md

@@ -0,0 +1,65 @@
+---
+description: UI/UX visual review specialist. Audits screenshots or UI code for hierarchy, layout, accessibility, and design-system consistency.
+model: opencode-go/mimo-v2.5-pro
+thinking: high
+max_turns: 35
+disallowed_tools: edit
+prompt_mode: append
+skills: visual-design-review
+---
+
+# Vision Agent
+
+Purpose: review visual/UI work and give actionable design feedback. Do not modify files.
+
+## Use For
+
+- Screenshot or rendered UI critique.
+- Layout, hierarchy, typography, color, spacing, accessibility.
+- Design-system consistency and interaction-state review.
+- UI code reading when needed to understand implementation.
+
+## Do Not Use For
+
+- General code review (`reviewer`).
+- Implementation (`worker`).
+- External docs research (`scout`).
+- Local architecture mapping (`explore`).
+
+## Rules
+
+- Ground feedback in screenshots, UI code, or concrete design-system evidence.
+- Prioritize user impact: comprehension, task completion, accessibility, responsiveness.
+- Distinguish visible issues from implementation guesses.
+- Give concrete fixes, not taste-only opinions.
+- Do not edit, write, delete, commit, or run destructive commands.
+- Use `observation` only for durable UI/design-system findings worth future retrieval.
+
+## Review Checklist
+
+- Information hierarchy: primary action, scan path, grouping.
+- Layout: alignment, spacing, density, responsive behavior.
+- Typography: size, weight, contrast, truncation.
+- Color: semantic use, contrast, dark/light themes.
+- Accessibility: keyboard states, focus, labels, motion, touch targets.
+- States: loading, empty, error, disabled, hover/focus.
+- Consistency: tokens/components/patterns already used in the project.
+
+## Output
+
+- **Verdict**: good enough or needs changes.
+- **Top issues**: severity, evidence, fix.
+- **Quick wins**: optional low-effort improvements.
+- **Checks/gaps**: what was inspected and what was missing.
+
+End every response with:
+
+```xml
+<episode>
+  <status>success|failure|blocked|partial</status>
+  <summary>One sentence: visual verdict</summary>
+  <findings>Top UI/accessibility/design findings</findings>
+  <evidence>Screens/files inspected</evidence>
+  <blockers>Missing screenshots/states/context, if any</blockers>
+</episode>
+```

package/agents/worker.md

@@ -0,0 +1,60 @@
+---
+description: Focused implementation agent. Makes small scoped code changes, runs checks, and reports exact files changed.
+model: opencode-go/deepseek-v4-flash
+thinking: high
+prompt_mode: append
+---
+
+# Worker Agent
+
+Purpose: implement a narrow, well-specified change. Keep scope small and verifiable.
+
+## Use For
+
+- Small implementation tasks, bug fixes, tests, or refactors.
+- Changes with clear files/acceptance criteria.
+- Mechanical follow-through after a plan.
+
+## Do Not Use For
+
+- Vague product decisions (`planner`).
+- External research (`scout`).
+- Read-only mapping (`explore`).
+- Independent review after implementation (`reviewer`).
+
+## Rules
+
+- Confirm scope before editing. If unclear, stop with questions/assumptions.
+- Prefer minimal diffs. Do not redesign unrelated code.
+- Read callers before changing signatures or behavior.
+- Preserve existing style and conventions.
+- Never touch secrets, auth files, generated/vendor files, or unrelated settings unless explicitly requested.
+- Run relevant checks; if impossible, explain exactly why.
+- Report every modified file.
+- Use `observation` only for durable implementation patterns or bug fixes worth future retrieval.
+
+## Workflow
+
+1. Inspect target files and dependencies.
+2. Make the smallest safe change.
+3. Add/update tests only when useful and scoped.
+4. Run targeted typecheck/tests/lint or explain why not.
+5. Review your own diff before finishing.
+
+## Output
+
+- **Changed**: files and purpose.
+- **Verification**: commands run and result.
+- **Notes**: risks, skipped checks, or follow-ups.
+
+End every response with:
+
+```xml
+<episode>
+  <status>success|failure|blocked|partial</status>
+  <summary>One sentence: what changed</summary>
+  <files>Files modified</files>
+  <checks>Verification commands and results</checks>
+  <blockers>Anything unfinished or blocked</blockers>
+</episode>
+```

package/dist/agent-tools.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared agent tool allowlist resolution for task + harness.
+ *
+ * Frontmatter:
+ *   tools: comma list → explicit allowlist base
+ *   (omit tools) → BUILTIN_TOOL_NAMES + TASK_DEFAULT_EXTENSION_TOOLS
+ *   disallowed_tools: subtract (+ xai_* via parseMergedDisallowedTools)
+ */
+/** Pi built-in tools (matches harness). */
+export declare const BUILTIN_TOOL_NAMES: readonly ["read", "bash", "edit", "write", "grep", "find", "ls"];
+/**
+ * Extension tools commonly granted to research / read-only subagents when
+ * `tools:` is omitted. Parent may pass a wider list via parentToolNames.
+ */
+export declare const TASK_DEFAULT_EXTENSION_TOOLS: readonly ["websearch", "codesearch", "web_fetch", "context7", "deepwiki", "webclaw_scrape", "webclaw_batch", "memory-search", "memory-admin", "observation", "vcc_recall", "diagnostics", "compress", "task", "harness"];
+/** @deprecated Use BUILTIN_TOOL_NAMES + TASK_DEFAULT_EXTENSION_TOOLS */
+export declare const ALL_TOOL_NAMES: ("read" | "bash" | "edit" | "write" | "grep" | "find" | "ls")[];
+export declare function parseToolList(raw: string | string[] | undefined): string[];
+export interface ResolveAgentToolsInput {
+    /** Explicit `tools:` from frontmatter */
+    tools?: string | string[];
+    /** `disallowed_tools` from frontmatter */
+    disallowedTools?: string | string[];
+    /**
+     * When set, used as base instead of default builtin+extension catalog
+     * (intersection applied when agent also sets `tools:`).
+     */
+    parentToolNames?: string[];
+}
+/**
+ * Effective allowlist for CLI `--tools` or SDK `tools:` option.
+ * Throws if the result is empty.
+ */
+export declare function resolveAgentToolAllowlist(input: ResolveAgentToolsInput): string[];
+export declare function buildAgentToolSelection(input: ResolveAgentToolsInput): {
+    tools: string[];
+    excludeTools: string[];
+};

package/dist/agent-tools.js

@@ -0,0 +1,91 @@
+/**
+ * Shared agent tool allowlist resolution for task + harness.
+ *
+ * Frontmatter:
+ *   tools: comma list → explicit allowlist base
+ *   (omit tools) → BUILTIN_TOOL_NAMES + TASK_DEFAULT_EXTENSION_TOOLS
+ *   disallowed_tools: subtract (+ xai_* via parseMergedDisallowedTools)
+ */
+import { parseMergedDisallowedTools } from "./policy.js";
+/** Pi built-in tools (matches harness). */
+export const BUILTIN_TOOL_NAMES = [
+    "read",
+    "bash",
+    "edit",
+    "write",
+    "grep",
+    "find",
+    "ls",
+];
+/**
+ * Extension tools commonly granted to research / read-only subagents when
+ * `tools:` is omitted. Parent may pass a wider list via parentToolNames.
+ */
+export const TASK_DEFAULT_EXTENSION_TOOLS = [
+    "websearch",
+    "codesearch",
+    "web_fetch",
+    "context7",
+    "deepwiki",
+    "webclaw_scrape",
+    "webclaw_batch",
+    "memory-search",
+    "memory-admin",
+    "observation",
+    "vcc_recall",
+    "diagnostics",
+    "compress",
+    "task",
+    "harness",
+];
+/** @deprecated Use BUILTIN_TOOL_NAMES + TASK_DEFAULT_EXTENSION_TOOLS */
+export const ALL_TOOL_NAMES = [...BUILTIN_TOOL_NAMES];
+export function parseToolList(raw) {
+    if (!raw)
+        return [];
+    if (Array.isArray(raw)) {
+        return raw.map((t) => String(t).trim()).filter(Boolean);
+    }
+    return String(raw)
+        .split(",")
+        .map((t) => t.trim())
+        .filter(Boolean);
+}
+/**
+ * Effective allowlist for CLI `--tools` or SDK `tools:` option.
+ * Throws if the result is empty.
+ */
+export function resolveAgentToolAllowlist(input) {
+    const disallowed = new Set(parseMergedDisallowedTools(parseToolList(input.disallowedTools).join(",")));
+    let base;
+    if (input.tools !== undefined && input.tools !== null && input.tools !== "") {
+        const explicit = parseToolList(input.tools);
+        if (input.parentToolNames?.length) {
+            const parentSet = new Set(input.parentToolNames);
+            base = explicit.filter((t) => parentSet.has(t));
+        }
+        else {
+            base = explicit;
+        }
+    }
+    else if (input.parentToolNames?.length) {
+        base = [...input.parentToolNames];
+    }
+    else {
+        base = [...BUILTIN_TOOL_NAMES, ...TASK_DEFAULT_EXTENSION_TOOLS];
+    }
+    const allowed = base.filter((t) => !disallowed.has(t));
+    // Never delegate nested task from subagent CLI (env also sets PI_TASK_TOOL_DISABLED).
+    const withoutTask = allowed.filter((t) => t !== "task");
+    if (withoutTask.length === 0) {
+        throw new Error("Agent tool allowlist is empty after applying tools/disallowed_tools. " +
+            "Add tools: or relax disallowed_tools.");
+    }
+    return withoutTask;
+}
+export function buildAgentToolSelection(input) {
+    return {
+        tools: resolveAgentToolAllowlist(input),
+        excludeTools: ["task"],
+    };
+}