Agent Catalog

An agent is a reusable definition of AI-agent work: a prompt, an engine, an input schema, and the set of tools the definition asks for. An agent is separate from the bindings that run it — an Agentic Job on a schedule, a Dispatch plan step, a manual run — so any number of bindings can reuse the same definition without re-authoring or re-approving it.

The catalog's trust model is simple: the definition requests capability; an admin grants it; enforcement reads only the grant. A repository sync can change what an agent asks for, but never what it has been granted.

Navigate to Organization Settings → Agents to browse the catalog. It has two tabs:

• Catalog — the governed agents of your organization, across all engines.
• Built-in — view-only fact sheets for the agents CodeCargo itself ships with (see Built-in Agents).

Where Agents Come From

Regardless of source, git is the source of truth for file-backed agents — the catalog row is a projection of the file plus the governance state (the grant) that a file cannot carry.

Browsing the Catalog

The catalog supports free-text search, an engine filter (CodeCargo / GitHub Actions / GitHub Copilot), a status filter, and an "N need review" chip that jumps straight to everything awaiting review. Each agent card shows:

• Engine badge and name, with the current status
• Capabilities: X of Y granted — the gap between requested and granted is the governance state at a glance
• The source repository and file path, linked to the definition in GitHub
• Engine-specific state: a Compiled / Not compiled badge on gh-aw agents, an Organization-wide badge on org-level Copilot agents, a naming-conflict warning when two Copilot definitions compete for one name
• A Dispatch chip when the agent is enabled for use in Dispatch plans, and a Pull request open link while a commit-to-repo PR is in flight

Opening an agent shows its full prompt, requested vs. granted tools (with approval-required and sensitive tools flagged), MCP server grants, source and reviewed revisions, model override, Where used (its bindings), and the recent run history of jobs bound to it.

Visibility

When you create an Agentic Job and write its prompt inline, CodeCargo records a private agent for you automatically — its capability ceiling is your own entitlements, so no admin grant is needed, and it never appears in the catalog. Use Save as reusable agent on the job to promote the definition to Org visibility. The existing grant carries forward; if you hold the publish permission the agent is published in the same act, otherwise it lands as Needs review and the job's runs pause until an admin approves. Promotion is one-way.

Lifecycle and Statuses

Any content change counts — the revision digest covers the whole file, so a prompt-only edit flips a published agent to Changed just like a tool change does. If a removed file returns to the default branch, the agent is resurrected as Needs review with its grants wiped; an explicit admin retirement sticks and is never undone by a scan.

There is no hard delete. Retire is a two-step action that first shows the blast radius — how many jobs will stop running.

Publishing and Tool Grants

Click Review on an agent that needs review (or Edit grant on a published one) to open a review of the exact current revision. The reviewer sees the full prompt, a change summary since the last review, and the requested capabilities:

• Tool grants — a checkbox per requested tool. The grant can only be equal to or narrower than the request; unticked tools simply aren't available to the agent, which fails that step rather than escalating.
• Approval-required tools — any granted tool can additionally require a human approval the first time each run uses it (see Agentic Jobs → Tool Approvals). Approval gates expand across tool implications, so a gate on file edits can't be routed around via shell.
• MCP server grants — bounded by both what the definition requests and each server's tool cap in the MCP catalog. A requested server your organization hasn't approved is flagged, not silently dropped.
• Dispatch — a separate checkbox controls whether Dispatch may use the agent in plans, independent of publication.

The grant is recorded against the reviewed revision. If the file changes between opening the review and approving it, the publish is refused rather than approving something the reviewer didn't read.

For GitHub-executed engines (gh-aw, Copilot), the review has no tool checkboxes — their tools are declared in the file and enforced by GitHub. Publishing those means only that CodeCargo may invoke them; the detail page shows the declared tools as informational badges.

Revision Pinning

Bindings reference an agent plus a git revision: pinned to a specific commit (reproducible — the run resolves its prompt from that exact revision) or floating on the default branch head. Floating is barred for agents holding sensitive tools — shell, file edits, issue creation, opening pull requests — so a reviewed definition can never change underneath its grant.

Committing an Agent to a Repository

UI-authored CodeCargo agents can be moved into git so they're reviewed and versioned like any other code. From the agent's detail page, Commit to repo writes .codecargo/agents/<name>.agent.md on a branch and opens a pull request — authored as you, with your GitHub access.

While the PR is open, the agent stays UI-authoritative and shows a Pull request open chip. When the PR merges, the next sync adopts the existing catalog entry rather than creating a duplicate: the agent becomes git-backed and read-only in the UI, and — because the definition changed hands — its grants are cleared and it re-enters review. From then on, edits flow through the file, and each change needs a fresh grant before it takes effect.

Built-in Agents

The Built-in tab lists the agents CodeCargo itself ships with — the ones behind platform features. It's a view-only fact sheet: their tool belts are defined in code and shown for visibility, and publish/grant decisions never apply to them.

Each agent's page groups its tools (platform reads, file edits, execution, and so on) with a read-only or mutating badge per tool, and notes where the agent runs.

Permissions Reference