feat(agent): add-on system with ztk as the first built-in

[joshsny]

Problem

PostHog Code tasks need a way to opt in to extra agent behaviors per-task — currently the only knobs are buried inside claudeCode.options or mcpServers, and there's no symmetric path for cloud and local. The first concrete use case is ztk (https://github.com/codejunkie99/ztk), a CLI that wraps shell commands to reduce LLM token consumption, but the surface should support future capabilities (PostHog-aware system-prompt addenda, MCP-based integrations, etc.) without bespoke plumbing each time.

Changes

Adds a typed add-on system to @posthog/agent and a task.options.add_ons configuration channel so a user can enable extensions by name when kicking off a task. Architecture:

• Unified registry, per-adapter capability honoring. packages/agent/src/add-ons/ defines AddOnDefinition (name, options schema, optional prepare, contribute) and AddOnRegistry. The same registry is consumed by both Claude and Codex adapters; each honors only the slots it can (Claude consumes all of env / systemPromptAppend / preToolUse / postToolUse; Codex consumes only systemPromptAppend because codex-acp exposes no pre-execution tool interception). Add-ons that need command rewriting declare supportedAdapters: ["claude"] and are skipped on Codex with a logged warning.
• Single transport channel. Add-on config rides on _meta.addOns of the ACP newSession request, alongside the existing claudeCode / jsonSchema channels. Resolved in ClaudeAcpAgent.createSession (Claude) and CodexAcpAgent.{newSession, loadSession, unstable_resumeSession, unstable_forkSession} (Codex).
• Cloud parity. AgentServerConfig.addOns and a matching --addOns <json> CLI flag on the sandbox agent server forward the same JSON onto the cloud newSession, so a task carries its add-ons regardless of where it runs.
• First built-in: ztk. ztkAddOn contributes a Claude PreToolUse hook that rewrites tool_input.command for Bash tool calls into ztk run [--skip-permissions] -- <original>. Options: binaryPath, skipPermissions. Binary resolution checks the configured path, then $PATH, then known install locations (/opt/homebrew/bin, /usr/local/bin, /usr/bin), then ~/.local/bin.
• Task model. Adds an optional options?: TaskOptions field (with add_ons inside) to both the agent-package Task type and the apps/code shared Task type, so the renderer and main process can populate it ahead of the Django migration.

Follow-ups not in this PR

• Django migration. The Django Task model needs options = models.JSONField(default=dict, blank=True) plus a matching serializer field. Until that lands the field is absent on every API response and add-ons can only be exercised programmatically (e.g. by callers that build _meta.addOns directly).
• UI. No task-creation UI changes yet — task.options.add_ons is settable from code but there's no "Add-ons" disclosure in the task input form.

How did you test this?

• Added 19 unit tests across registry.test.ts (empty config, env merging with last-wins precedence, systemPromptAppend concatenation, pre/postToolUse aggregation, adapter gating, unknown-name warnings, options-validation failure, prepare/contribute ordering, prepare failures propagate, duplicate-registration rejection) and ztk.test.ts (options schema rejects invalid input, missing-binary errors from prepare, Bash command rewriting, non-Bash pass-through, --skip-permissions, Codex skipped via adapter gating, end-to-end registry resolution, double-wrap protection, single-quote escaping for paths with quotes).
• pnpm --filter agent typecheck clean.
• pnpm --filter agent test src/add-ons — 19/19 pass. Pre-existing options.test.ts (3) still pass.
• Did not run a live ztk-wrapped session against Claude; the hook surface and rewriting are exercised in unit tests but a smoke test with a real ztk binary is a sensible pre-merge check.

Publish to changelog?

no

---

Created with PostHog Code