Skip to content

docs(adr): define exact Pi extension tool selection - #9265

Draft
eshulman2 wants to merge 1 commit into
fullsend-ai:mainfrom
eshulman2:docs/adr-0166-pi-tools
Draft

eshulman2 wants to merge 1 commit into
fullsend-ai:mainfrom
eshulman2:docs/adr-0166-pi-tools

Conversation

@eshulman2

Copy link
Copy Markdown
Contributor

Summary

Record the decision to select exact native Pi extension tools without widening access. A vetted extension can load today while its declared native tool name is dropped by strict tool translation.

Related Issue

Split from #9261 so each PR contains one decision and only its related living-document changes. Implementation is tracked in #9254; this documentation PR does not implement or close that issue.

Changes

  • Add ADR 0166: resolve exact names against vetted extensions and fail before inference when a requested tool is missing or ambiguous.
  • Keep the effective selection explicit, including empty selections, and preserve hook identity and child permission intersections.
  • Update the living architecture and related security/agent problem documents. No recovery or multi-target ADR is included.

Forge-neutral: the same Pi runtime contract applies on GitHub, GitLab and Forgejo. Coordinate implementation with #9179 rather than duplicating its MCP and child-permission changes.

Current-behavior evidence

Inspected baseline: 7455751ecb9446953527dbf73b4e379ea5442cb0.

Testing

  • Changes staged before make lint; applicable ADR, link, secret and Semgrep checks pass.
  • git diff --check passes.
  • Documentation only: no runtime, dispatch or external publication behavior is implemented, and no live acceptance is claimed.

Checklist

  • Conventional Commit title.
  • Human-directed commit signed off for DCO.
  • I wrote this contribution myself and can explain all changes in it.

Prepared with coding-agent assistance; the contributor can assess the personal-authorship attestation.

Signed-off-by: eshulman2 <ellashulman1@gmail.com>
@eshulman2
eshulman2 requested a review from a team as a code owner November 10, 2026 10:08
@github-actions

Copy link
Copy Markdown

E2E tests did not run

E2E tests run automatically for pull requests authored by users with write access or higher.

For other contributors, someone with write access must add the ok-to-test label after the latest push.

Reason: unauthorized

See E2E testing guide for details.

@qodo-code-review

Copy link
Copy Markdown

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Grey Divider

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Grey Divider

Tip of the day
💡 Did you know, you can move or hide resolved findings to focus on what still needs action

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

@qodo-code-review

Copy link
Copy Markdown

PR Summary by Qodo

Document exact, least-privilege Pi extension tool selection

📝 Documentation 🕐 20-40 Minutes

Grey Divider

AI Description

• Add ADR 0166 to define exact selection of tools from vetted Pi extensions.
• Require missing or ambiguous tools to fail before inference, without widening access.
• Link the decision from architecture, agent, and security documentation; runtime support remains
 unimplemented.
Diagram

graph TD
  A["Agent allowlist"] --> B["Built-in mapping"] --> C["Native resolver"] --> D{"Unique match?"} -->|Yes| F["Explicit tool set"] --> G["Hook and child"]
  E["Vetted extensions"] --> C
  B -->|Built-in| F
  D -->|No| H["Setup failure"]
Loading
High-Level Assessment

The ADR's exact-name resolution against vetted extensions best preserves the existing strict allowlist. Removing the allowlist would widen access, while hardcoding extension names would couple independently versioned resources to runner releases. Keep implementation and denial testing as separate follow-up work.

Files changed (4) +88 / -0

Documentation (4) +88 / -0
0166-select-pi-extension-tools-without-widening-access.mdDefine the Pi extension tool selection decision +74/-0

Define the Pi extension tool selection decision

• Records exact native-name resolution against vetted extensions, pre-inference failure for missing or ambiguous names, and an explicit effective tool set. Defines hook identity, child-permission, integrity, and forge-neutral boundaries; notes that implementation and real-Pi denial tests remain required.

docs/ADRs/0166-select-pi-extension-tools-without-widening-access.md

architecture.mdRecord the pending selection contract in the living architecture +4/-0

Record the pending selection contract in the living architecture

• Adds ADR 0166 to the runtime architecture and marks exact selection, explicit empty sets, and pre-inference failure as decided but not yet implemented.

docs/architecture.md

agent-architecture.mdConnect agent permissions to ADR 0166 +4/-0

Connect agent permissions to ADR 0166

• Links the agent architecture discussion to the decision that native Pi extension permissions must not enable default tools.

docs/problems/agent-architecture.md

security-threat-model.mdDocument the extension-tool least-privilege boundary +6/-0

Document the extension-tool least-privilege boundary

• States that selecting one tool must not grant sibling or default tools, and links exact selection to consistent hook and child permissions.

docs/problems/security-threat-model.md

@ascerra ascerra left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm for this. I hit the same limit with a small extension (code): once tools: names a built-in, Pi hides the extension tools, so I had to leave tools: off entirely (note).

One thing that may help now: with tools: left off, extension tools already run on fullsend. I ran them in a GitLab pipeline on v0.55.0 (results). So the CVE extension may not need to wait for this to run, only to be locked down. I haven't tried that extension itself.

Two questions inline.

Comment on lines +54 to +58
The effective tool set is explicit, including when empty. Hook authorization
uses the same canonical native name. Child runs, if supported, load the vetted
code that supplies a requested tool and receive only the intersection of
parent and child permissions. A runtime path that cannot enforce this refuses
the selection. Repository discovery cannot supply tools or alter identity;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What should the same agent file do on a runtime that doesn't load the extension?

This is not a blocker for the CVE work, since we're going Pi first. But tools: is written once for every runtime, and the adopter picks the runtime.

Today my agent runs on both because it declares no tools. Pi calls the extension tools, and Claude Code runs the same commands through Bash. If I list the tools:

  • Does Claude Code ignore them or refuse the run?
  • Adding Bash for Claude Code gives Pi a shell too.

If this is for Pi-only agents, could the ADR say so?

Comment on lines +47 to +50
Keep existing built-in translations. Treat an otherwise unmapped exact name
as a requested native extension tool, and resolve it only after loading the
runner-vetted extension set. A missing or ambiguous requested tool fails the
run before inference. It never falls back to all extension tools, Pi defaults

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Today an unmapped name is dropped with a warning (internal/runtime/pi_bootstrap.go). After this it fails the run. I think that's right, but it is a behavior change for custom agents that list a Claude-only tool.

Could the ADR note that, and say how the runner tells a Claude-only built-in like WebFetch from a missing extension tool?

Our own agents only list Bash and Skill, so they're fine.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants