docs(adr): Agent registration

docs/ADRs/0045-forge-portable-harness-schema.md

@@ -742,3 +742,4 @@ forge-specific artifact. The harness and agent definition are portable.
 - [Issue #101](https://github.com/fullsend-ai/fullsend/issues/101): Forge-agnostic agent interface
 - [Issue #322](https://github.com/fullsend-ai/fullsend/issues/322): Platform-specific component identification
 - [Issue #1986](https://github.com/fullsend-ai/fullsend/issues/1986): Default agents should use the same delivery mechanism as custom agents
+- [ADR 0058](0058-agent-registration.md): Agent registration — re-adds `agents` config key with URL/path semantics (supersedes the role/name/slug schema removed in Phase 4)

docs/ADRs/0058-agent-registration.md

@@ -0,0 +1,89 @@
+---
+title: "58. Agent registration"
+status: Accepted
+relates_to:
+  - agent-architecture
+  - agent-infrastructure
+topics:
+  - agents
+  - per-repo
+  - configuration
+  - extensibility
+---
+
+# 58. Agent registration
+
+Date: 2026-06-29
+
+## Status
+
+Accepted
+
+## Context
+
+Which agents fullsend knows about is currently compiled into the binary.
+Scaffold-embedded harnesses (`internal/scaffold/fullsend-repo/harness/`)
+define the complete agent set, and `HarnessNames()` enumerates them
+from the embed. There is no mechanism for registering agents that live
+outside the scaffold — adding or extracting an agent requires a code
+change to the fullsend binary.
+
+The triage agent extraction to `fullsend-ai/agents`
+([ADR 0045](0045-forge-portable-harness-schema.md) Phase 4) is the
+first agent to move out of the scaffold. The registration mechanism
+must support both first-party extractions and user-defined agents
+without code changes.
+
+## Decision
+
+Make agent registration a **config-level concept**. Add an `agents`
+list to both `OrgConfig` and `PerRepoConfig`. (Note: ADR 0045 Phase 4
+previously removed the `agents` block from `OrgConfig`; this re-adds
+a field with the same YAML key but different semantics — harness
+source URLs rather than role/name/slug identity tuples.) Each entry
+is a URL or local path, with an optional name override:
+
+```yaml
+agents:
+  - https://raw.githubusercontent.com/fullsend-ai/agents/<sha>/harness/triage.yaml#sha256=<hash>
+  - name: lint
+    source: harness/my-linter.yaml
+```
+
+`fullsend run <name>` resolves agents from config at runtime, loading
+harnesses directly from URLs or local paths. No intermediate wrapper
+files are generated on disk — role and slug come from the harness
+content itself. Config entries merge additively with
+scaffold-discovered agents; collision is keyed by agent name (explicit
+`name` if set, otherwise derived from source filename) and resolved in
+favor of config, enabling gradual migration. Once all first-party agents are extracted, config
+becomes authoritative and the scaffold fallback is removed.
+
+A `fullsend agent` CLI subcommand (`add`, `list`, `update`, `remove`)
+manages entries (single-user CLI operations; no concurrency guard on
+config read/write) and auto-pins URLs to a commit SHA with an
+integrity hash. Per-repo config gains `allowed_remote_resources` so per-repo
+installs can validate base composition without an org config repo.
+Per-repo config is read from the **base branch**, not the PR branch,
+so a PR cannot inject an attacker-controlled `allowed_remote_resources`
+entry or agent source.
+
+See the [implementation plan](../plans/agent-registration.md) for
+phasing, schema details, CLI behavior, and migration mechanics.
+
+## Consequences
+
+- Anyone can add an agent to a fullsend installation via `fullsend agent add` — no code change required.
+- First-party and third-party agents follow the same registration path.
+- The additive merge model allows agents to be extracted from the scaffold one at a time without disrupting existing installations.
+- Per-repo installs no longer need org config for remote resource validation.
+- No forced migration — empty config falls back to scaffold discovery until populated.
+- The `agents` YAML key was previously used in `OrgConfig` with a different schema (role/name/slug identity tuples, removed by ADR 0045 Phase 4). The new schema (URL/path source entries) is incompatible; a custom unmarshaler detects and rejects old-format entries with a clear error message.
+
+## References
+
+- [ADR 0033](0033-per-repo-installation-mode.md) -- per-repo installation mode
+- [ADR 0038](0038-universal-harness-access.md) -- URL-based resource references and integrity hashes
+- [ADR 0045](0045-forge-portable-harness-schema.md) -- harness composition via `base:` URLs
+- [ADR 0057](0057-repos-management.md) -- repos management for per-repo installations
+- [Implementation plan](../plans/agent-registration.md)

docs/architecture.md

@@ -227,6 +227,13 @@ The registry is the bridge between the abstract roles defined in [agent-architec
 
 Fullsend provides a base set of agent definitions. The adopting organization's **`.fullsend`** repository extends this with org-specific agents in its `agents/` directory, following the inheritance model: fullsend defaults, then org config, then per-repo overrides. (See [ADR 0003](ADRs/0003-org-config-repo-convention.md).)
 
+**Decided:**
+
+- Config-level agent registration: an `agents` list in both `OrgConfig` and `PerRepoConfig` declares agent harness sources as pinned URLs or local paths, replacing compiled-in agent discovery ([ADR 0058](ADRs/0058-agent-registration.md)).
+- Runtime resolution: `fullsend run <name>` looks up the agent in config and loads the harness directly from the URL or path — no intermediate wrapper files on disk. Role and slug come from the harness content itself.
+- Additive merge: config entries overlay scaffold-discovered agents (config wins on name collision), enabling gradual extraction of first-party agents without disrupting existing installations. Builds on [ADR 0045](ADRs/0045-forge-portable-harness-schema.md) harness identity model.
+- CLI management: `fullsend agent add/list/update/remove` manages config entries and auto-pins URLs to a commit SHA with an integrity hash.
+
 **Open questions:**
 
 - How are new agent roles added, tested, and promoted to production? (See [testing-agents.md](problems/testing-agents.md).) (Functional tests provide a framework for testing agent roles against controlled fixtures — [ADR 0052](ADRs/0052-functional-tests-for-agent-pipelines.md). Promotion workflow remains open.)