feat(pi-ext-gate): @agentic-kit/pi-ext-gate — policy + remote approvals for pi tool calls

[pyramation]

Summary

Package 5 of the additive @agentic-kit/* series (planning issue #1657): what makes an unattended cloud run safe to start. Tool calls are gated by a declared policy (data, not code paths), and anything the policy won't decide alone is deferred to an approval channel that reaches a human on another machine over the platform's existing rows/API — no socket back into the cluster.

The mechanism is small because pi's tool_call handler can await:

pi.on('tool_call', async (event) => {
  const verdict = policy.evaluate({ toolName: event.toolName, input: event.input });
  const settled = verdict.decision === 'ask'
    ? await approvals.request({ runId, toolCallId, toolName, input, reason, requestedAt })  // suspends this tool only
    : verdict;
  return settled.decision === 'allow' ? {} : { block: true, reason: settled.reason ?? … };
});

Decisions worth reading the code for:

• The default is ask, not allow. A tool nobody declared isn't implicitly trusted, and denying it outright would strand the run. First matching rule wins, and a rule can narrow on arguments (match: ({ input }) => /\brm\b/.test(String(input.command))).
• A policy that can produce ask with no approvals channel throws at construction, not on the first sensitive tool call.
• Timeouts deny. pollingApprovalChannel is the DB-rendezvous baseline (submit a row, poll for the decision); if nobody decides within timeoutMs the answer is deny — an unattended run must not act unapproved just because nobody was watching. onTimeout: 'allow' opts out.
• A channel failure is not an approval — submit/poll errors propagate and the tool call fails rather than degrading into a silent allow. staticApprovalChannel({ decision: 'allow' }) exists so "approve everything" has to be written down.
• onDecision emits every settled decision (policy verdict, final decision, deciding actor, timestamp) — the record the run log / audit trail stores. The block reason is the model's only explanation for a refusal, so policy reasons are written for the model to read.

Nothing here touches the network or a model: the policy is pure, the channel takes an injected clock/sleep, and the extension is driven through a fake ExtensionAPI (21 tests). Registered in the agentic CI shard.

This branch is stacked on #1723 → #1724 → #1725 → #1726, so its diff against main carries those packages until they merge.

Link to Devin session: https://app.devin.ai/sessions/450ce6d6659c47759c184ae6ec19a2a8
Requested by: @pyramation

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring