@cad0p/pi-subagents-tintinweb 0.14.2-20260814.3

package/SECURITY.md

@@ -0,0 +1,95 @@
+# Security Policy
+
+This document explains the security model behind `@cad0p/pi-subagents-tintinweb` and
+where the boundaries are.
+
+`pi-subagents` is a [pi](https://pi.dev) extension. It spawns and orchestrates
+autonomous sub-agents that run locally within the same security boundary as the
+user running pi, and inherit pi's trust model. It is the responsibility of the
+user to monitor those agents' operations or to contain them within a container,
+virtual machine, or other sandbox solution.
+
+Sub-agents run with the local user account's privileges and can use the tools
+they are granted (reading and writing files, running commands, network access,
+etc.). They treat the local user account and files writable by that account as
+inside the same trust boundary as the pi process itself. If an attacker can
+modify files under the user's home directory, workspace, shell startup files,
+environment, pi configuration, or this extension's configuration, they can
+generally influence pi, its sub-agents, or other local developer tools. Reports
+that depend on such prior local write access are not security vulnerabilities
+unless they demonstrate how `pi-subagents` grants that write access or crosses an
+operating-system privilege boundary.
+
+`pi-subagents` relies on the user only loading trustworthy agent definitions
+(`.pi/agents/*.md`, `.agents/agents/*.md`, and global agents), skills, and
+tools, and only using pi within trusted repositories. Files like `AGENTS.md`,
+custom agent frontmatter/system prompts, preloaded skills, or instructions
+embedded in repository content and comments can be used to prompt-inject the
+coding agent and its sub-agents trivially, and this cannot be protected against.
+
+## Reporting a Vulnerability
+
+If you believe you found a security vulnerability in `pi-subagents`, please
+report it privately by opening a draft advisory through
+[GitHub Security Advisories](https://github.com/tintinweb/pi-subagents/security/advisories/new)
+for this repository.
+
+Please include:
+
+- A description of the issue and its impact
+- Steps to reproduce, proof of concept, or relevant logs
+- Affected version, commit, or configuration
+- Any known mitigations
+
+Do not open a public issue for security-sensitive reports. Reports will be
+reviewed and disclosure coordinated as appropriate.
+
+## Scope
+
+Security issues in the published npm package and the code in this repository are
+in scope — for example, a flaw in `pi-subagents` that crosses an
+operating-system privilege boundary, or that causes the extension to bypass a
+tool restriction, denylist, or agent boundary it claims to enforce.
+
+## Out Of Scope
+
+- Local code execution or sandboxing behavior (sub-agents intentionally do not
+  have a sandbox and run with the user's privileges)
+- Behavior of pi itself, or of other pi extensions, skills, or tools installed by
+  the user (report those to their respective projects)
+- Risks from working in untrusted repositories
+- Risks from installing or loading untrusted agent definitions, skills,
+  extensions, packages, or tools
+- Issues caused by non-trustworthy MITM proxies
+- Public internet exposure of a pi installation
+- Prompt injection attacks (including via `AGENTS.md`, agent frontmatter, custom
+  system prompts, preloaded skills, repository content, or context inheritance)
+- Exposed secrets that are third-party/user-controlled credentials
+- Reports requiring the ability to create, modify, delete, or replace files,
+  directories, symlinks, environment variables, shell configuration, or other
+  user-controlled local state on the target machine. This includes `.pi/agents/`,
+  `.agents/agents/`, agent and extension configuration, persistent agent memory,
+  workspace files, `AGENTS.md`, skills, dotfiles, and files synchronized through NFS, roaming
+  profiles, or dotfile managers, unless the report shows how `pi-subagents`
+  itself grants that access.
+- Issues caused by intentionally weakened user configuration
+- Resource/DOS claims that require trusted local input/config
+- Reports about malicious model output
+- User-approved or user-initiated local actions presented as vulnerabilities
+
+## Notes for Reporters
+
+The most useful reports show a current, reproducible security boundary bypass
+with demonstrated impact. Reports that only show expected local-agent behavior,
+prompt injection, or a malicious trusted agent definition/skill are not security
+vulnerabilities under this model.
+
+For example, a report showing that malicious contents written to a trusted agent
+definition or extension configuration cause a sub-agent to execute commands, load
+attacker-controlled tools, or send credentials to an attacker-controlled endpoint
+is out of scope.
+
+When possible, include the exact affected path, package version or commit SHA,
+configuration, and a proof of concept against the latest release or latest
+`master`. For dependency reports, include evidence that the shipped dependency is
+affected and that the issue is reachable through `pi-subagents`.

package/examples/agent-tool-description.md

@@ -0,0 +1,41 @@
+Launch a new agent to handle complex, multi-step tasks autonomously. Each agent type has specific capabilities and tools available to it.
+
+Available agent types and the tools they have access to:
+{{typeList}}
+
+Custom agents can be defined in .pi/agents/<name>.md (project) or {{agentDir}}/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones. Creating a .md file with the same name as a default agent overrides it.
+
+When using the Agent tool, specify a subagent_type parameter to select which agent type to use.
+
+## When not to use
+
+If the target is already known, use a direct tool — `read` for a known path, `grep`/`find` for a specific symbol or string. Reserve this tool for open-ended questions that span the codebase, or tasks that match an available agent type.
+
+## Usage notes
+
+- Always include a short (3-5 word) description summarizing what the agent will do (shown in UI).
+- When you launch multiple agents for independent work, send them in a single message with multiple tool uses, with run_in_background: true on each, so they run concurrently. If the user specifies that they want agents run "in parallel", you MUST send a single message with multiple tool calls. Foreground calls run sequentially — only one executes at a time.
+- When the agent is done, it returns a single message back to you. The result is not visible to the user — to show the user, send a text message with a concise summary.
+- Trust but verify: an agent's summary describes what it intended to do, not necessarily what it did. When an agent writes or edits code, check the actual changes before reporting work as done.
+- Use run_in_background for work you don't need immediately. You will be notified when it completes — do NOT poll or sleep waiting for it. Continue with other work or respond to the user instead.
+- Foreground vs background: use foreground (default) when you need the agent's results before you can proceed. Use background when you have genuinely independent work to do in parallel.
+- Use resume with an agent ID to continue a previous agent's work. A new (non-resume) Agent call starts a fresh agent with no memory of prior runs, so the prompt must be self-contained.
+- Use steer_subagent to send mid-run messages to a running background agent.
+- Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, etc.), since it is not aware of the user's intent.
+- If an agent's description says it should be used proactively, try to use it without the user having to ask for it first.
+- Use thinking to control extended thinking level.
+- Use inherit_context if the agent needs the parent conversation history.
+- Use isolation: "worktree" to run the agent in an isolated git worktree (safe parallel file modifications). The worktree is automatically cleaned up if the agent makes no changes; otherwise the path and branch are returned in the result.{{scheduleGuideline}}
+
+## Writing the prompt
+
+Provide clear, detailed prompts so the agent can work autonomously. Brief it like a smart colleague who just walked into the room — it hasn't seen this conversation, doesn't know what you've tried, doesn't understand why this task matters.
+- Explain what you're trying to accomplish and why.
+- Describe what you've already learned or ruled out.
+- Give enough context about the surrounding problem that the agent can make judgment calls rather than just following a narrow instruction.
+- If you need a short response, say so ("report in under 200 words").
+- Lookups: hand over the exact command. Investigations: hand over the question — prescribed steps become dead weight when the premise is wrong.
+
+Terse command-style prompts produce shallow, generic work.
+
+**Never delegate understanding.** Don't write "based on your findings, fix the bug" or "based on the research, implement it." Those phrases push synthesis onto the agent instead of doing it yourself. Write prompts that prove you understood: include file paths, line numbers, what specifically to change.

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@cad0p/pi-subagents-tintinweb",
+  "version": "0.14.2-20260814.3",
+  "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
+  "author": "tintinweb",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cad0p/pi-subagents-tintinweb.git"
+  },
+  "homepage": "https://github.com/cad0p/pi-subagents-tintinweb#readme",
+  "bugs": {
+    "url": "https://github.com/cad0p/pi-subagents-tintinweb/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "subagent",
+    "agent",
+    "autonomous"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.80.0",
+    "@earendil-works/pi-coding-agent": ">=0.80.0",
+    "@earendil-works/pi-tui": ">=0.80.0"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.49",
+    "croner": "^10.0.1",
+    "nanoid": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "vitest run e2e --reporter=verbose",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/ test/",
+    "lint:fix": "biome check --fix src/ test/"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.0",
+    "vitest": "^4.0.18",
+    "@earendil-works/pi-ai": ">=0.80.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,12 @@
+# pnpm 11 blocks native build scripts by default and exits non-zero
+# ([ERR_PNPM_IGNORED_BUILDS]) when any are unapproved. This package's
+# transitive dependencies (pulled in through the @earendil-works/pi-* peers)
+# ship install scripts; without an approval entry `pnpm install` returns a
+# failing exit code, which breaks pi's git-package reconciliation
+# (git clean -fdx -> pnpm install -> non-zero -> extension fails to load).
+# Approving them here makes `pnpm install` exit 0.
+allowBuilds:
+  "@google/genai": true
+  esbuild: true
+  koffi: false
+  protobufjs: true