take the agent-create and forge-token responses from swarm-controller-api

swarmctl decoded POST /api/agents and POST /api/agents/{name}/forge-token
into hand-written copies of the controller's private response structs.
Both now live in swarm-controller-api, so a field renamed on one side is a
compile error on the other. Wire format and OpenAPI schema are unchanged.

The request side stays mirrored: CreateAgentRequest carries inference
settings and an ArchetypeRef (swarm-queue-client types) and Permission
(hive-sh4re), and the permissions body is a list of Permission. Where
those types live is #5471's decision.

Files:
- swarm-controller-api/src/agents.rs, lib.rs: the two responses, with
  round-trip tests whose literals come from the tests that move here.
- swarm-controller/src/main.rs: imports them; the struct definitions and
  create_agent_warning_tests (now in the api crate) go.
- swarmctl/src/agent.rs: imports them; the mirrors and their decode tests
  go, and the module doc says only the request is mirrored now.
- swarmctl/src/permissions.rs: its doc pointed at agent.rs for why it
  mirrors; that reason no longer covers Permissions, so it gives its own.
- swarmctl/README.md, swarm-controller-api/README.md, CLAUDE.md: which
  bodies are shared and which are mirrored.

Part of #5472

swarmctl/src/agent.rs

@@ -13,11 +13,11 @@
 //! over the socket rather than pulling in a full client stack for one
 //! POST.
 //!
-//! The two shapes below **mirror** the controller's own private
-//! `CreateAgentRequest` / `CreateAgentResponse` rather than sharing them:
-//! this crate does not link `swarm-controller`, and they are not in
-//! `swarm-controller-api`. The seam is narrow and both ends validate, so
-//! drift surfaces as a 400 naming the field.
+//! The responses come from `swarm-controller-api`. The request body below
+//! **mirrors** the controller's own private `CreateAgentRequest`, whose
+//! fields include types from `swarm-queue-client` and `hive-sh4re`, and
+//! `swarm-controller-api` depends on neither. The seam is narrow and both
+//! ends validate, so drift surfaces as a 400 naming the field.
 //!
 //! Long-form rationale for all three: `swarmctl/README.md`.
 
@@ -26,7 +26,8 @@ use std::path::Path;
 use anyhow::{Context as _, Result, bail};
 use http_body_util::{BodyExt as _, Full};
 use hyper_util::rt::TokioIo;
-use serde::{Deserialize, Serialize};
+use serde::Serialize;
+use swarm_controller_api::agents::{CreateAgentResponse, MintAgentForgeTokenResponse};
 use tokio::net::UnixStream;
 
 use crate::remote::Target;
@@ -42,23 +43,6 @@ struct CreateAgentRequest<'a> {
     hive: &'a str,
 }
 
-/// Success body of `POST /api/agents`.
-#[derive(Deserialize)]
-struct CreateAgentResponse {
-    node_id: u64,
-    /// Name collisions the controller **allowed through** — it is the
-    /// "warn now, refuse later" step, so an empty list is the normal case
-    /// and the field is omitted from the JSON entirely when it is empty.
-    #[serde(default)]
-    warnings: Vec<String>,
-}
-
-/// Success body of `POST /api/agents/{name}/forge-token`, which takes no body.
-#[derive(Deserialize)]
-struct MintForgeTokenResponse {
-    node_id: u64,
-}
-
 /// Run `swarmctl agent create`.
 ///
 /// Synchronous on purpose: every other verb in this crate is, and this is
@@ -113,7 +97,7 @@ pub(crate) fn mint_forge_token(target: &Target, name: &str) -> Result<()> {
         .enable_all()
         .build()
         .context("starting a tokio runtime for the controller request")?;
-    let resp: MintForgeTokenResponse = rt.block_on(post(
+    let resp: MintAgentForgeTokenResponse = rt.block_on(post(
         target,
         &format!("/api/agents/{name}/forge-token"),
         &serde_json::json!({}),
@@ -283,25 +267,7 @@ fn connect_hint(socket: &Path) -> String {
 
 #[cfg(test)]
 mod tests {
-    use super::{CreateAgentResponse, describe_error, parse_ident};
-
-    /// The endpoint omits `warnings` entirely when there are none, so the
-    /// normal response must still decode — a missing field here would make
-    /// every successful creation fail to parse.
-    #[test]
-    fn a_response_without_warnings_decodes() {
-        let resp: CreateAgentResponse =
-            serde_json::from_str(r#"{"node_id":7}"#).expect("the normal shape decodes");
-        assert_eq!(resp.node_id, 7);
-        assert!(resp.warnings.is_empty());
-    }
-
-    #[test]
-    fn warnings_are_carried_through() {
-        let resp: CreateAgentResponse =
-            serde_json::from_str(r#"{"node_id":9,"warnings":["reserved name"]}"#).expect("decodes");
-        assert_eq!(resp.warnings, vec!["reserved name".to_owned()]);
-    }
+    use super::{describe_error, parse_ident};
 
     /// The whole point of parsing problem+json: the 400 for an unknown
     /// hive carries the roster of hives that would have worked, and that

swarmctl/src/permissions.rs

@@ -5,9 +5,10 @@
 //! it restarts it, after its current turn, when `manage_root_agent` changes.
 //! Unset leaves the agent on the default set; an empty list grants nothing.
 //!
-//! The shape below mirrors the controller's `Permissions`, for the reason
-//! [`crate::agent`]'s module doc gives. Permission names are checked by the
-//! controller, which answers 422 for one it does not know.
+//! The shape below mirrors the controller's `Permissions`, whose names are
+//! `hive_sh4re::permissions::Permission`, and `swarm-controller-api` does not
+//! depend on `hive-sh4re`. Permission names are checked by the controller,
+//! which answers 422 for one it does not know.
 
 use anyhow::{Context as _, Result};
 use serde::{Deserialize, Serialize};