Mental model

Learn the objects you configure and audit.

Agents do the work. Agent identities name the caller. Capability grants define what they can touch. Approvals pause exact risky calls. The activity log records mediated calls.

How the Pieces Fit

Keep four choices separate: who owns the agent loop, which model provider it uses, whether the task has a machine, and which capability calls ExecWarden governs. These choices combine. A hosted session does not automatically mean full machine access, and an external client does not mean ungoverned access.

Agent loop

ExecWarden-hosted session, or an external client such as Codex CLI, Claude Code, or OpenCode.

Model provider

The model credential used by the loop. Model choice does not decide where shell, files, or tools execute.

Execution

Lightweight hosted JavaScript and bounded public HTTP where enabled, or connected customer compute for machine access.

Shared governed authority

Per-tool grants, resource scope, approvals, expiry, revocation, and activity records apply to capability calls mediated by ExecWarden across the supported agent and execution paths.

Core Objects

Workspace	The ownership boundary for sessions, workflows, credentials, package secrets, integrations, Agent identities, and feature flags.
Execution environment	The machine boundary for files, shell, browser, git, previews, private-network access, and any secrets that already live there.
Session	A hosted-agent context with model choice, transcript, governed tools, and linked durable runs. Lightweight gateway-backed runs may work without a machine; the current environment-backed interactive path requires connected execution capacity.
Agent identity	A named persistent caller credential for external agents and MCP clients. It has lifecycle, expiry, revocation, token regeneration, grants, and an activity log.
Capability	A discoverable action surface with schemas, scope contract, source metadata, maximum mode, risk hints, and activity-recording defaults.
Capability grant	The active Ask or Allow record that binds a subject to one capability with scope, expiry, use limits, capture mode, provenance, and lifecycle. Off is the absence of a grant.
Human input request	A stored pause where a package asks a person to approve, choose, provide text, or explicitly resume before the source session continues.
Workflow	A durable automation object: definition, triggers, outputs, access rules, and enabled state.
Trigger	The event that starts a workflow. Manual, schedule, GitHub webhook/GitHub App events, custom webhook receiver events, and declared package events execute today; broader product-event publishers and richer trigger UI are follow-up work.
Run	One workflow execution, with status, timestamps, trigger input, logs, approvals, artifacts, and optional agent-session links.

How to Talk About a Run

Work

The agent inspects, edits, calls tools, runs commands, or produces an artifact.

Access

The gateway exposes only the APIs, repos, docs, and internal tools granted to the run.

Human review

Sensitive writes can pause for approval, while packages can also ask for choices, missing values, reasons, or an explicit resume.

History

The transcript, outputs, human input decisions, approval records, activity records, and workflow run history stay inspectable later.