fix(hooks): improve agent-scoped hook error messaging

internal/gateway/methods/hooks.go

@@ -145,8 +145,9 @@ func (m *HookMethods) handleCreate(ctx context.Context, client *gateway.Client,
 			i18n.T(locale, i18n.MsgMasterScopeRequired)))
 		return
 	}
-	// For tenant/agent scope, fill TenantID from ctx if not provided.
-	if cfg.Scope != hooks.ScopeGlobal && cfg.TenantID == uuid.Nil {
+	// For tenant/agent-scoped hooks, fill TenantID from ctx if not provided or sentinel.
+	if (cfg.Scope == hooks.ScopeTenant || cfg.Scope == hooks.ScopeAgent) &&
+		(cfg.TenantID == uuid.Nil || cfg.TenantID == hooks.SentinelTenantID) {
 		cfg.TenantID = store.TenantIDFromContext(ctx)
 	}
 	if cfg.Scope == hooks.ScopeGlobal {

internal/hooks/config.go

@@ -94,7 +94,7 @@ func (h *HookConfig) validateScope() error {
 		}
 	case ScopeAgent:
 		if h.TenantID == SentinelTenantID || h.TenantID == uuid.Nil {
-			return fmt.Errorf("hook: agent scope requires a real tenant_id")
+			return fmt.Errorf("agent-scoped hooks cannot be created in the master/system tenant. Please create a workspace tenant first")
 		}
 		if len(h.AgentIDs) == 0 {
 			if h.AgentID != nil && *h.AgentID != uuid.Nil {

ui/web/src/pages/hooks/components/hook-form-dialog.tsx

@@ -33,6 +33,7 @@ interface HookFormDialogProps {
 export function HookFormDialog({ open, onOpenChange, onSubmit, initial }: HookFormDialogProps) {
   const { t } = useTranslation("hooks");
   const isMasterScope = useAuthStore((s) => s.isMasterScope);
+  const currentTenantId = useAuthStore((s) => s.tenantId);
   // Global scope hidden for non-master callers; existing `global` hooks still render as-is in edit mode.
   const scopeOptions = isMasterScope
     ? (["global", "tenant", "agent"] as const)
@@ -43,9 +44,11 @@ export function HookFormDialog({ open, onOpenChange, onSubmit, initial }: HookFo
     formState: { errors, isSubmitting },
   } = useForm<HookFormData>({
     resolver: zodResolver(hookFormSchema),
+    mode: "onSubmit",
     defaultValues: {
       name: "",
       agent_ids: [],
+      tenant_id: "",
       event: "pre_tool_use",
       handler_type: "script",
       scope: "tenant",
@@ -80,6 +83,7 @@ export function HookFormDialog({ open, onOpenChange, onSubmit, initial }: HookFo
         reset({
           name: initial.name ?? "",
           agent_ids: initial.agent_ids ?? [],
+          tenant_id: initial.tenant_id ?? "",
           event: initial.event as HookFormData["event"],
           handler_type: handlerType,
           scope: initial.scope,
@@ -105,6 +109,10 @@ export function HookFormDialog({ open, onOpenChange, onSubmit, initial }: HookFo
   }, [open, initial, reset]);
 
   const onFormSubmit = async (data: HookFormData) => {
+    // Auto-fill tenant_id for agent-scoped hooks from current auth context
+    if (data.scope === "agent" && !data.tenant_id) {
+      data.tenant_id = currentTenantId;
+    }
     await onSubmit(data);
     onOpenChange(false);
   };
@@ -408,7 +416,7 @@ export function HookFormDialog({ open, onOpenChange, onSubmit, initial }: HookFo
           <Button variant="outline" onClick={() => onOpenChange(false)} disabled={isSubmitting}>
             {t("form.cancel")}
           </Button>
-          <Button onClick={handleSubmit(onFormSubmit)} disabled={isSubmitting}>
+          <Button onClick={(e) => handleSubmit(onFormSubmit)(e as any)} disabled={isSubmitting}>
             {t(isBuiltin ? "form.saveToggle" : "form.save")}
           </Button>
         </DialogFooter>

ui/web/src/schemas/hooks.schema.ts

@@ -22,6 +22,7 @@ export const hookFormSchema = z
   .object({
     name: z.string().max(255).optional(),
     agent_ids: z.array(z.string()).optional(),
+    tenant_id: z.string().uuid().or(z.literal("")).optional(),
     event: HookEventEnum,
     handler_type: HookHandlerTypeEnum,
     scope: HookScopeEnum,