Tools + Approvals (Implementation): pipeline + exec approvals

This is an implementation guide for tool policy and exec approvals.

Entry points (concept):

• Tool policy + exec approvals
• Sandbox vs tool policy vs elevated

Code entry points (optional)

• src/agents/pi-tools.ts
• src/agents/tool-policy-pipeline.ts
• src/agents/pi-tools.before-tool-call.ts
• src/agents/pi-tool-definition-adapter.ts
• src/infra/exec-approvals.ts
• src/gateway/exec-approval-manager.ts
• src/gateway/server-methods/exec-approval.ts

Two main lines you’re building

1. A tool policy pipeline (explainable allow/deny).
2. An exec approval state machine (observable two-phase gate).

Tool policy pipeline (five steps)

1. owner-only pruning
2. layered policy filtering (fixed order)
3. schema normalization
4. before_tool_call injection (patch/block)
5. optional abort-signal wrapping

Exec approvals: request → wait → resolve → timeout

Minimum behaviors:

• idempotent waitDecision for the same approval id
• timeouts resolve to null (caller handles explicitly)
• short grace retention for resolved entries (two-phase race protection)

Failure modes and troubleshooting

• waitDecision can’t find an id: verify “register before accepted response” ordering; cross-check Gateway protocol.
• Missing after_tool_call audits: ensure failure paths also trigger after_tool_call and it runs fire-and-forget.

Acceptance checks

1. Pipeline order is fixed and explainable (“which layer filtered the tool”).
2. before_tool_call can patch/block; after_tool_call runs on success and failure.
3. Approvals time out and recover (no infinite hangs).
4. Adjusted-params tracking is bounded (no unbounded growth under load).