AGENT CONTROL PLANE SPEC (ACP-1)

Use this as a pre-implementation spec for any agent feature that can call tools or change external state.

1) Workflow Definition
- Name the workflow (e.g., “Create Jira bugs from support tickets”).
- Trigger: user chat, scheduled job, webhook, or button.
- Success criteria: what observable outcome means it worked.
- Non-goals: explicitly list what it must not attempt.

2) Tool Inventory (Allowlist)
For each tool call the agent may use:
- Tool name (stable ID, versioned).
- Description in plain language.
- Input schema (typed; max lengths; required/optional fields).
- Output schema (what you store; what you show).
- Side effects: none / reversible / irreversible.
- Idempotency strategy: idempotency key required for any side effect.

3) Identity + Permissions (Principals)
Define a principal per tool:
- End-user principal: OAuth scopes and consent screen text.
- Service account principal: permissions and where keys live.
- Delegated escalation: how it’s granted, time-bound rules, and audit fields.
- Explicitly ban “shared token for all tools.”

4) Approval Policy (Modes)
Set mode per tool and per risk level:
- Dry-run: agent proposes actions only.
- Human-in-the-loop: approval required before execution.
- Auto: executes without approval.
For each mode, define:
- UI surface: where approvals appear (queue, notification).
- Timeout behavior: what happens if no one approves.

5) Data Boundaries
- Inputs: which data sources the agent can read (and which are forbidden).
- Output destinations: where the agent can write.
- PII/sensitive data handling: what must be redacted before logging.
- Tenant isolation rules for multi-tenant systems.

6) Memory Plan
Split memory into:
A) Operational state
- What you store for replay/debugging.
- Retention period and deletion mechanism.
B) User profile memory
- What qualifies as “stable preference/fact.”
- User controls: view/edit/delete.
- Default: opt-in vs opt-out (choose one and document it).

7) Observability + Audit
Minimum required logs per run:
- Timestamped tool calls with inputs/outputs (structured JSON).
- Principal used for each call.
- Approval events (who approved, when).
- Error taxonomy (validation error, auth error, tool timeout, policy violation).
Add replay support:
- Ability to rerun with the same tool inputs in a sandbox.

8) Safety + Abuse Cases
Write at least five abuse scenarios:
- Prompt injection leading to unauthorized tool call.
- Data exfiltration via a “harmless” connector.
- Accidental mass action (bulk email, bulk delete).
- Cross-tenant data access.
- Stale memory causing wrong action.
For each, define the guardrail: schema validation, allowlist, approval, rate limit, or explicit deny.

9) Launch Gate
Do not ship until:
- Every tool is typed, validated, and allowlisted.
- Per-tool principal and scopes are defined.
- Approval mode exists for irreversible actions.
- Audit logs can answer: who/what/when/why for every tool call.

If you can’t fill this in with concrete rules, you’re not ready to ship an agent. You’re ready to ship a demo.