Patterns

Pick the first agent task to govern.

Choose by the system the agent touches and the risky action you want to control: repo work, reports, internal APIs, operations tasks, or event-triggered work.

Choose a First Task

Pick the first real job by the system the agent needs to touch and the risky action you want to control. Start narrow: one connected system, one grant, one review point, and one Activity record to inspect.

Agent can change code	Use the GitHub Repo Quickstart: one repo, one review-branch pattern, Ask-mode PR actions, and no merge authority until you grant it separately.
Agent should only report	Grant read access to one repo, package, or imported MCP tool. Ask for a finished report, then inspect the transcript, tool calls, and Activity record.
Agent needs one private API	Wrap the endpoint as a capability package, grant the one action the task needs, and put any state-changing call in Ask mode.
Task should start from an event	Verify the webhook event, start a workflow with the same scoped tools, and pause before comments, deploys, credits, or other writes.

Cross-System Authority Pattern

Use the GitHub quickstart when code is the first system you want an agent to touch safely: repo, branch, PR, approval, and revocation are all easy to inspect. The same authority loop also applies when a task crosses an alert source, an issue tracker, GitHub, and a team notification surface. For systems that are not built in, connect a remote MCP server or wrap the internal API as a package-backed tool.

Connect	Bring the alert source, issue tracker, GitHub, Slack or another notification surface, and any internal API behind workspace-owned credentials.
Identify	Create one Agent identity for the incident or support assistant, with a short expiry and a label that will make Activity readable later.
Grant	Start with read access to alert and issue context, repo clone/fetch, and only the package or MCP actions needed for the task.
Approve	Put issue creation/update, PR create/update, merge, customer-facing messages, deploys, and team notifications in Ask mode until the pattern is routine.
Inspect	Review Activity for caller, connector or package, capability, grant scope, exact approval payload, provider result, and cleanup state before widening access.

1. Claude or Codex plus GitHub

Goal: let an external agent client or hosted Codex-style session inspect a repo, edit in a sandbox, run tests, push only to an allowed review branch, then review the PR before any merge authority is used.

Setup	Connect the workspace GitHub integration. Start with the target repo in the Git remote allowlist. For hosted work, attach a sandbox volume so the agent has shell, file, browser, and git tools.
Current capabilities	`github:pull_requests.get`, `github:pull_requests.files.list`, `github:pull_requests.commits.list`, `github:issues.comments.list`, and the gateway smart-HTTP git remote for clone/fetch/push. PR creation uses `github:pull_requests.create`.
Sandbox work	The system instructions include a gateway git URL. The agent clones it inside the sandbox, edits files, runs the repo test command, and shows `git diff`, test output, branch name, and intended PR title/body.
Review point	Before opening or updating a PR, the agent should show owner/repo, branch, base, diff summary, test command/result, and the exact PR payload. Branch pushes are constrained by the gateway git branch allowlist. Merge remains a separate explicit-only GitHub action and should require a narrow grant or approval.
Audit result	The transcript, tool calls, policy or approval decision, execution status, and pushed branch or PR URL stay attached to the session. Downstream GitHub Actions are a second hop after push and should be treated as part of the risk review.

Capability plan
- Agent identity: Codex repo review
- Repo: acme/payments-api
- Git remote: allow clone/fetch and review-branch push
- Branches: fix/*, feature/*, drafts/*
- PR create/update/comment/review: Ask mode
- Merge: absent unless separately granted for a reviewed run

Uses in this walkthrough	Canonical grants, Git remote repo allowlists, hosted sandbox sessions, gateway git clone/fetch/push URLs, branch allowlists, exact-call approvals for GitHub API actions, PR create/update actions, and explicit PR merge authority.
Boundary to keep	Treat branch pushes and PR API calls as different controls: pushes must match the gateway branch allowlist; PR creation/update can be approval-gated; merge is explicit-only and should stay review-driven.
Related docs	Hosted Agents, Gateway Capabilities, Approvals & Policy, Workflows, and Security Model.

2. Incident or Support Ops Assistant

Goal: let an assistant investigate an operational issue or customer escalation across several systems, propose the exact next action, collect a ticket or reason, then execute only after approval.

Setup	Connect built-in systems where they fit, such as GitHub for deploy context. If the work starts from an alert or provider callback, create a webhook receiver whose handler emits workflow events. For support, observability, billing, ticketing, or task follow-up, register package-backed tools or scoped external MCP tools.
Current platform pieces	Use read-only GitHub actions, external MCP tools, and package actions you register, such as `pkg:support-desk:tickets.get`, `pkg:billing:customer.get`, or `pkg:observability:alerts.get`. Mutations go through package staging actions and `userInputRequest`.
Investigation phase	The assistant reads the alert or support ticket, gathers recent context, summarizes evidence, and proposes one of a few concrete next actions instead of immediately mutating customer or production state.
Proposed action	The proposal names the affected customer/service, current state, intended external action, exact params, expected result, rollback or follow-up, and the ticket or incident id that explains why it is allowed.
Approval point	If a ticket id, reason, or customer-facing message is missing, the package asks for free text first. Once complete, the approve choice follows up to the exact same-package mutation, such as posting an escalation note or committing a staged mitigation.
Audit result	The transcript keeps the evidence and reasoning. ExecWarden stores the input request, approval-shaped decision, followup action, execution status, and package result.

return {
  ok: true,
  userInputRequest: {
    title: "Escalate customer incident",
    summary: "Post escalation note to ticket SUP-9182 and page the payments owner.",
    input: {
      kind: "single_choice",
      choices: [
        {
          id: "approve",
          label: "Escalate",
          followup: {
            capability: "pkg:support-ops:incident.escalate.commit",
            params: { stagedMutationId: "mut_support_01J4..." }
          }
        },
        { id: "reject", label: "Cancel" }
      ]
    }
  }
};

Uses in this walkthrough	Webhook receivers, hosted sessions, read-only GitHub context, imported MCP connections, API-key package tools, package-local secrets, generic human input requests, approval-shaped followups, Activity records, and manual or event-triggered workflow runs.
Boundary to keep	Support, billing, observability, and production systems should be package-backed or scoped MCP tools unless they are built-in capabilities in your workspace.
Related docs	Gateway Capabilities, Capability Packages, Human Input, Approvals & Policy, Workflows, and Security Model.

3. Internal Production API or Package

Goal: wrap an internal production API so an agent can inspect state, stage a mutation, collect a reason and ticket, ask for approval, commit the exact staged payload, and leave an audit record.

Setup	Create a capability package such as `prod-admin`. Declare only the API key or storage token names it needs. Configure those secrets after package creation so they are not in source, prompts, or sandbox environment variables.
Current capabilities	Read actions such as `pkg:prod-admin:deployments.get`, a staging action such as `pkg:prod-admin:deployment.scale.stage`, and a commit action such as `pkg:prod-admin:deployment.scale.commit`. Package actions can return `userInputRequest`.
Stage phase	The package reads current production state, builds the provider payload, stores it in package-owned storage with workspace id and idempotency key, and returns a preview instead of calling the production mutation endpoint.
Human input	The staged action asks for a reason or ticket with free text when missing. Once it has the reason, it returns an approve/reject request whose approve choice follows up to the same-package commit action with the staged mutation id.
Commit phase	On approval, the package claims the staged mutation, verifies the payload is still valid, calls the internal API using the package-local secret, records the remote response, and returns the audit id and final state.
Audit result	ExecWarden stores the human input request, approval-shaped decision, followup action, execution status, and source session context. The package-owned storage records staged, committed, or discarded state keyed by workspace.

return {
  ok: true,
  userInputRequest: {
    title: "Scale production deployment",
    summary: "Scale payments-api in prod from 6 to 8 replicas. Ticket: INC-1842.",
    input: {
      kind: "single_choice",
      choices: [
        {
          id: "approve",
          label: "Scale to 8",
          style: "danger",
          followup: {
            capability: "pkg:prod-admin:deployment.scale.commit",
            params: { stagedMutationId: "mut_01J4..." }
          }
        },
        { id: "reject", label: "Cancel" }
      ]
    }
  }
};

Uses in this walkthrough	API-key JavaScript and Wasm packages, package-local secrets, explicit canonical package grants, runtime isolation, package-owned storage patterns, generic human input requests, approval-shaped followups, Activity, and MCP/package invocation.
Boundary to keep	Package code runs in the isolated package runtime and should receive only declared package-local secrets, never raw workspace credentials in prompts or sandbox environment variables.
Related docs	Capability Packages, Package Storage, Human Input, Approvals & Policy, and MCP & API.

4. Webhook-Driven Workflow

Goal: let an external producer send a signed webhook, normalize it in a small JavaScript handler, publish a workflow event, and start a repeatable workflow with the event payload.

Setup	Open the Webhooks page and start the setup agent, or start a generic agent session with webhook management and workflow admin access. The agent should fetch the webhook setup guide and workflow guide before saving anything.
Receiver	Create a custom receiver for producers such as incident, billing, or CI systems. Use a source like `webhook:incident-router` and document expected event types such as `incident.created`. For GitHub, use the GitHub preset instead of custom code.
Handler	The handler runs in the safe Wasm JS runtime. For custom third-party producers, it verifies the provider signature with the receiver secret, checks the parsed request shape, emits only `{ type, idempotencyKey, value }`, and returns accept, ignore, or reject. ExecWarden assigns the receiver source automatically.
Simulation	Before sending live traffic, the agent should simulate the stored or draft handler with representative headers and body. Simulation checks handler behavior without recording a delivery or publishing workflow events.
Workflow	Create an enabled workflow with an event trigger that matches the receiver source and emitted event type. The handler value arrives in the workflow as `ctx.input.event`; trigger metadata arrives as `ctx.input.trigger`.
Audit result	Receiver list/get views show recent deliveries, emitted event ids and types, observed event summaries, and workflow run evidence. Payload sample values are visible only to users with webhook management permission.

async (input, webhook) => {
  const expected = "sha256=" + webhook.crypto.hmacSha256Hex(input.receiver.secret, input.rawBodyText);
  const actual = input.headers["x-incident-signature"] || "";
  if (!webhook.crypto.timingSafeEqual(actual, expected)) {
    return webhook.reject(401, "invalid signature");
  }
  if (input.bodyParseError) {
    return webhook.reject(400, input.bodyParseError);
  }
  const body = input.body && typeof input.body === "object" ? input.body : {};
  const incidentId = typeof body.id === "string" ? body.id : null;
  const eventId = input.headers["x-incident-event-id"];

  if (!incidentId) {
    return webhook.reject(400, "missing incident id");
  }

  if (!eventId) {
    return webhook.reject(400, "missing incident event id");
  }

  webhook.emit({
    type: "incident.created",
    idempotencyKey: eventId,
    value: {
      incidentId,
      severity: body.severity ?? "unknown",
      title: body.title ?? "Untitled incident",
      receiverId: input.receiver.id
    }
  });
  return webhook.accept();
}

Uses in this walkthrough	Webhook receivers, JavaScript handlers in the Wasm runtime, handler simulation, provider signature verification, workflow event triggers, event idempotency keys, and workflow run history.
Boundary to keep	Workflows subscribe to normalized events, not raw webhooks. Keep provider parsing in the handler, keep workflow logic in the workflow, and use stable provider delivery ids for idempotency when they exist.
Related docs	Webhook Events, Workflows, Gateway Capabilities, Approvals & Policy, and Security Model.

Other Work That Fits

These are not separate products or promises of first-party connector depth. They are places where the same pattern applies: start read-only, constrain the useful write, ask for missing context when needed, and inspect the record before widening scope.

Repo maintenance

Inspect code, patch in a sandbox, run tests, then review branch pushes and approve API writes such as PR creation, comments, or merges.

Incident response

Receive alert webhooks as workflow events; read logs, runbooks, and recent deploys through packages or scoped tools; collect ticket/reason; approve the exact action.

Customer support ops

Read ticket, customer, billing, and product state through package-backed tools; draft a reply; stage a refund, credit, or escalation.

Internal API workbench

Turn private endpoints into package-backed tools with schemas, package-local secrets, staged mutations, and audit records.

Finance admin

Read invoices, vendors, expenses, or subscriptions through custom packages; stage corrections or payments with reviewer-visible params.

Compliance evidence

Gather GitHub, Drive, task, package, or MCP data into a repeatable evidence packet without write authority.

Release manager

Check CI, open risks, changelog, and deploy readiness; review branch updates and approve PR or package-backed release actions.

Webhook-driven workflows

Create GitHub-preset or custom JavaScript webhook receivers that verify producers, emit normalized events, and start workflows by source/type subscription.

Policy Example: Repo Review Agent

Use this shape when an external Codex or Claude session should inspect real code, prepare a branch, and leave a bounded paper trail instead of receiving broad GitHub credentials.

Caller	Codex MCP client acting through the Agent identity labeled Codex repo review, scoped to one workspace.
Allowed resources	Gateway Git remote access is limited to acme/api and acme/web. GitHub REST calls must include owner/repo params that match the same allowlist.
Allowed arguments	Git pushes must target `agent/*` branches. Main/master are blocked even if the branch pattern is misconfigured.
Approval boundary	Configured GitHub REST writes, package writes, and external MCP writes can pause for approval. For Git code changes, use branch limits plus PR review; merge is separate explicit authority.
Denied authority	Merge is absent unless a canonical grant explicitly includes the merge action. Admin/package-management actions are absent.
Expiration	Canonical grants can expire after a use limit or timestamp. Agent identities can carry expiresAt, and can still be revoked or disabled when access should stop immediately.