feat: add ReportsToPicker for agent management

- Introduced ReportsToPicker component in AgentConfigForm and NewAgent pages to allow selection of an agent's manager.
- Updated organizational structure documentation to reflect the ability to change an agent's manager post-creation.
- Enhanced error handling in ConfigurationTab to provide user feedback on save failures.

docs/guides/board-operator/org-structure.md

@@ -9,6 +9,7 @@ Paperclip enforces a strict organizational hierarchy. Every agent reports to exa
 
 - The **CEO** has no manager (reports to the board/human operator)
 - Every other agent has a `reportsTo` field pointing to their manager
+- You can change an agent’s manager after creation from **Agent → Configuration → Reports to** (or via `PATCH /api/agents/{id}` with `reportsTo`)
 - Managers can create subtasks and delegate to their reports
 - Agents escalate blockers up the chain of command
 

ui/src/components/AgentConfigForm.tsx

@@ -44,6 +44,7 @@ import { ClaudeLocalAdvancedFields } from "../adapters/claude-local/config-field
 import { MarkdownEditor } from "./MarkdownEditor";
 import { ChoosePathButton } from "./PathInstructionsModal";
 import { OpenCodeLogoIcon } from "./OpenCodeLogoIcon";
+import { ReportsToPicker } from "./ReportsToPicker";
 
 /* ---- Create mode values ---- */
 
@@ -301,6 +302,12 @@ export function AgentConfigForm(props: AgentConfigFormProps) {
   });
   const models = fetchedModels ?? externalModels ?? [];
 
+  const { data: companyAgents = [] } = useQuery({
+    queryKey: selectedCompanyId ? queryKeys.agents.list(selectedCompanyId) : ["agents", "none", "list"],
+    queryFn: () => agentsApi.list(selectedCompanyId!),
+    enabled: Boolean(!isCreate && selectedCompanyId),
+  });
+
   /** Props passed to adapter-specific config field components */
   const adapterFieldProps = {
     mode,
@@ -447,6 +454,15 @@ export function AgentConfigForm(props: AgentConfigFormProps) {
                 placeholder="e.g. VP of Engineering"
               />
             </Field>
+            <Field label="Reports to" hint={help.reportsTo}>
+              <ReportsToPicker
+                agents={companyAgents}
+                value={eff("identity", "reportsTo", props.agent.reportsTo ?? null)}
+                onChange={(id) => mark("identity", "reportsTo", id)}
+                excludeAgentIds={[props.agent.id]}
+                chooseLabel="Choose manager…"
+              />
+            </Field>
             <Field label="Capabilities" hint={help.capabilities}>
               <MarkdownEditor
                 value={eff("identity", "capabilities", props.agent.capabilities ?? "")}

ui/src/components/ReportsToPicker.tsx

@@ -0,0 +1,96 @@
+import { useState } from "react";
+import type { Agent } from "@paperclipai/shared";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover";
+import { User } from "lucide-react";
+import { cn } from "../lib/utils";
+import { roleLabels } from "./agent-config-primitives";
+import { AgentIcon } from "./AgentIconPicker";
+
+export function ReportsToPicker({
+  agents,
+  value,
+  onChange,
+  disabled = false,
+  excludeAgentIds = [],
+  disabledEmptyLabel = "Reports to: N/A (CEO)",
+  chooseLabel = "Reports to...",
+}: {
+  agents: Agent[];
+  value: string | null;
+  onChange: (id: string | null) => void;
+  disabled?: boolean;
+  excludeAgentIds?: string[];
+  disabledEmptyLabel?: string;
+  chooseLabel?: string;
+}) {
+  const [open, setOpen] = useState(false);
+  const exclude = new Set(excludeAgentIds);
+  const rows = agents.filter(
+    (a) => a.status !== "terminated" && !exclude.has(a.id),
+  );
+  const current = value ? agents.find((a) => a.id === value) : null;
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          className={cn(
+            "inline-flex items-center gap-1.5 rounded-md border border-border px-2 py-1 text-xs hover:bg-accent/50 transition-colors",
+            disabled && "opacity-60 cursor-not-allowed",
+          )}
+          disabled={disabled}
+        >
+          {current ? (
+            <>
+              <AgentIcon icon={current.icon} className="h-3 w-3 text-muted-foreground" />
+              {`Reports to ${current.name}`}
+            </>
+          ) : (
+            <>
+              <User className="h-3 w-3 text-muted-foreground" />
+              {disabled ? disabledEmptyLabel : chooseLabel}
+            </>
+          )}
+        </button>
+      </PopoverTrigger>
+      <PopoverContent className="w-48 p-1" align="start">
+        <button
+          type="button"
+          className={cn(
+            "flex items-center gap-2 w-full px-2 py-1.5 text-xs rounded hover:bg-accent/50",
+            value === null && "bg-accent",
+          )}
+          onClick={() => {
+            onChange(null);
+            setOpen(false);
+          }}
+        >
+          No manager
+        </button>
+        {rows.map((a) => (
+          <button
+            type="button"
+            key={a.id}
+            className={cn(
+              "flex items-center gap-2 w-full px-2 py-1.5 text-xs rounded hover:bg-accent/50 truncate",
+              a.id === value && "bg-accent",
+            )}
+            onClick={() => {
+              onChange(a.id);
+              setOpen(false);
+            }}
+          >
+            <AgentIcon icon={a.icon} className="shrink-0 h-3 w-3 text-muted-foreground" />
+            {a.name}
+            <span className="text-muted-foreground ml-auto">{roleLabels[a.role] ?? a.role}</span>
+          </button>
+        ))}
+      </PopoverContent>
+    </Popover>
+  );
+}

ui/src/pages/AgentDetail.tsx

@@ -17,6 +17,7 @@ import { issuesApi } from "../api/issues";
 import { usePanel } from "../context/PanelContext";
 import { useSidebar } from "../context/SidebarContext";
 import { useCompany } from "../context/CompanyContext";
+import { useToast } from "../context/ToastContext";
 import { useDialog } from "../context/DialogContext";
 import { useBreadcrumbs } from "../context/BreadcrumbContext";
 import { queryKeys } from "../lib/queryKeys";
@@ -1356,6 +1357,7 @@ function ConfigurationTab({
   updatePermissions: { mutate: (permissions: AgentPermissionUpdate) => void; isPending: boolean };
 }) {
   const queryClient = useQueryClient();
+  const { pushToast } = useToast();
   const [awaitingRefreshAfterSave, setAwaitingRefreshAfterSave] = useState(false);
   const lastAgentRef = useRef(agent);
 
@@ -1377,9 +1379,17 @@ function ConfigurationTab({
       queryClient.invalidateQueries({ queryKey: queryKeys.agents.detail(agent.id) });
       queryClient.invalidateQueries({ queryKey: queryKeys.agents.detail(agent.urlKey) });
       queryClient.invalidateQueries({ queryKey: queryKeys.agents.configRevisions(agent.id) });
+      queryClient.invalidateQueries({ queryKey: queryKeys.agents.list(agent.companyId) });
     },
-    onError: () => {
+    onError: (err) => {
       setAwaitingRefreshAfterSave(false);
+      const message =
+        err instanceof ApiError
+          ? err.message
+          : err instanceof Error
+            ? err.message
+            : "Could not save agent";
+      pushToast({ title: "Save failed", body: message, tone: "error" });
     },
   });
 

ui/src/pages/NewAgent.tsx

@@ -12,13 +12,13 @@ import {
   PopoverContent,
   PopoverTrigger,
 } from "@/components/ui/popover";
-import { Shield, User } from "lucide-react";
+import { Shield } from "lucide-react";
 import { cn, agentUrl } from "../lib/utils";
 import { roleLabels } from "../components/agent-config-primitives";
 import { AgentConfigForm, type CreateConfigValues } from "../components/AgentConfigForm";
 import { defaultCreateValues } from "../components/agent-config-defaults";
 import { getUIAdapter } from "../adapters";
-import { AgentIcon } from "../components/AgentIconPicker";
+import { ReportsToPicker } from "../components/ReportsToPicker";
 import {
   DEFAULT_CODEX_LOCAL_BYPASS_APPROVALS_AND_SANDBOX,
   DEFAULT_CODEX_LOCAL_MODEL,
@@ -66,10 +66,9 @@ export function NewAgent() {
   const [name, setName] = useState("");
   const [title, setTitle] = useState("");
   const [role, setRole] = useState("general");
-  const [reportsTo, setReportsTo] = useState("");
+  const [reportsTo, setReportsTo] = useState<string | null>(null);
   const [configValues, setConfigValues] = useState<CreateConfigValues>(defaultCreateValues);
   const [roleOpen, setRoleOpen] = useState(false);
-  const [reportsToOpen, setReportsToOpen] = useState(false);
   const [formError, setFormError] = useState<string | null>(null);
 
   const { data: agents } = useQuery({
@@ -173,7 +172,7 @@ export function NewAgent() {
       name: name.trim(),
       role: effectiveRole,
       ...(title.trim() ? { title: title.trim() } : {}),
-      ...(reportsTo ? { reportsTo } : {}),
+      ...(reportsTo != null ? { reportsTo } : {}),
       adapterType: configValues.adapterType,
       adapterConfig: buildAdapterConfig(),
       runtimeConfig: {
@@ -189,8 +188,6 @@ export function NewAgent() {
     });
   }
 
-  const currentReportsTo = (agents ?? []).find((a) => a.id === reportsTo);
-
   return (
     <div className="mx-auto max-w-2xl space-y-6">
       <div>
@@ -253,54 +250,12 @@ export function NewAgent() {
             </PopoverContent>
           </Popover>
 
-          <Popover open={reportsToOpen} onOpenChange={setReportsToOpen}>
-            <PopoverTrigger asChild>
-              <button
-                className={cn(
-                  "inline-flex items-center gap-1.5 rounded-md border border-border px-2 py-1 text-xs hover:bg-accent/50 transition-colors",
-                  isFirstAgent && "opacity-60 cursor-not-allowed"
-                )}
-                disabled={isFirstAgent}
-              >
-                {currentReportsTo ? (
-                  <>
-                    <AgentIcon icon={currentReportsTo.icon} className="h-3 w-3 text-muted-foreground" />
-                    {`Reports to ${currentReportsTo.name}`}
-                  </>
-                ) : (
-                  <>
-                    <User className="h-3 w-3 text-muted-foreground" />
-                    {isFirstAgent ? "Reports to: N/A (CEO)" : "Reports to..."}
-                  </>
-                )}
-              </button>
-            </PopoverTrigger>
-            <PopoverContent className="w-48 p-1" align="start">
-              <button
-                className={cn(
-                  "flex items-center gap-2 w-full px-2 py-1.5 text-xs rounded hover:bg-accent/50",
-                  !reportsTo && "bg-accent"
-                )}
-                onClick={() => { setReportsTo(""); setReportsToOpen(false); }}
-              >
-                No manager
-              </button>
-              {(agents ?? []).map((a) => (
-                <button
-                  key={a.id}
-                  className={cn(
-                    "flex items-center gap-2 w-full px-2 py-1.5 text-xs rounded hover:bg-accent/50 truncate",
-                    a.id === reportsTo && "bg-accent"
-                  )}
-                  onClick={() => { setReportsTo(a.id); setReportsToOpen(false); }}
-                >
-                  <AgentIcon icon={a.icon} className="shrink-0 h-3 w-3 text-muted-foreground" />
-                  {a.name}
-                  <span className="text-muted-foreground ml-auto">{roleLabels[a.role] ?? a.role}</span>
-                </button>
-              ))}
-            </PopoverContent>
-          </Popover>
+          <ReportsToPicker
+            agents={agents ?? []}
+            value={reportsTo}
+            onChange={setReportsTo}
+            disabled={isFirstAgent}
+          />
         </div>
 
         {/* Shared config form */}