Problem between pgfkeys, tikz and personal macro

This happens because shape, color names (and some other stuff) are not keys. In other words, when you write red or diamond it doesn't have a dedicated key for such things. Hence, it goes through the TikZ machinery of searchname/.retry but because no such key is there it fails. Instead /tikz/.unknown/.code is much more comprehensive and sophisticated. For example

{%
        % Ok, second chance: This might be an arrow specification:
        \expandafter\pgfutil@in@\expandafter-\expandafter{\tikz@key}%
        \ifpgfutil@in@%
          % Ah, an arrow spec!
          \expandafter\tikz@processarrows\expandafter{\tikz@key}%
        \else%
          % Ok, third chance: A shape!
          \expandafter\ifx\csname pgf@sh@s@\tikz@key\endcsname\relax%
            \pgfkeys{/errors/unknown key/.expand
            once=\expandafter{\expandafter/\expandafter t\expandafter
            i\expandafter k\expandafter z\expandafter/\tikz@key}{##1}}%
          \else%
            \edef\tikz@shape{\tikz@key}%
          \fi%
        \fi%
      }%

I can think of two ways to do this:

1. You can in the end of the key trial, pass to TikZ explicitly and let it decide what to do. Hence you add the following

   \pgfkeys{/mykeys/.cd,
   d/.store in            = {\macro@d},   
   a/.store in            = {\macro@a},
   /mykeys/.unknown/.code = {\let\searchname=\pgfkeyscurrentname%
                             \pgfkeysalso{\searchname/.try=#1,
                             /tikz/\searchname/.retry=#1,
                             /tikz/.cd,#1}% <--- Now invoked under TikZ
                            }
   }  
   

   Here, we explicitly trigger TikZ unknown machinery since the family is TikZ now. Hence goes through all the shape name checks and so on.

2. Write your own /.unknown/.code handler to account for known names. For example in Make a PGFkeys path take precedence over another path for a whole scope there are a few examples.

Here is two simple solutions.

First solution (the better ?)

You may use the /.search also handler (see p.891 of pgfmanual, v3.0.1a):

\documentclass[a4paper]{article}
\usepackage{tikz}
\usetikzlibrary{calc}

\makeatletter
\pgfkeys{
  /mykeys/.cd,
  d/.code                     = {\def\macro@d{#1}},   
  a/.code                     = {\def\macro@a{#1}},
  /mykeys/.search also={/tikz},
}  
\def\mainmacro{\pgfutil@ifnextchar[{\main@macro}{\main@macro[]}}
\def\main@macro[#1](#2)#3{%
\begingroup
  \pgfkeys{mykeys/.cd,
           d = 1,
           a = 45}
  \pgfqkeys{/mykeys}{#1}
  \path (#2) --+(\macro@a:\macro@d) node[/mykeys/.cd,#1] {#3};
\endgroup
}
\makeatother

\begin{document} 

    \begin{tikzpicture}
        \draw (0,0) --( 1,1) coordinate (a) ;
        \mainmacro[a=0,d=12pt,draw,red,shape=circle](a){label 1}    
        \mainmacro[d=2cm,draw,circle](a){label 2}       
    \end{tikzpicture}

\end{document}

Second solution

You may use the /.forward to handler (see p.890 of pgfmanual, v3.0.1a):

\documentclass[a4paper]{article}
\usepackage{tikz}
\usetikzlibrary{calc}

\makeatletter
\pgfkeys{
  /mykeys/.cd,
  d/.code                     = {\def\macro@d{#1}},   
  a/.code                     = {\def\macro@a{#1}},
  /mykeys/.unknown/.forward to=/tikz/\pgfkeyscurrentname,
}  
\def\mainmacro{\pgfutil@ifnextchar[{\main@macro}{\main@macro[]}}
\def\main@macro[#1](#2)#3{%
\begingroup
  \pgfkeys{mykeys/.cd,
           d = 1,
           a = 45}
  \pgfqkeys{/mykeys}{#1}
  \path (#2) --+(\macro@a:\macro@d) node[/mykeys/.cd,#1] {#3};
\endgroup
}
\makeatother

\begin{document} 
    \begin{tikzpicture}
        \draw (0,0) --( 1,1) coordinate (a) ;
        \mainmacro[a=0,d=12pt,draw,red,shape=circle](a){label 1}    
        \mainmacro[d=2cm,draw,circle](a){label 2}       
    \end{tikzpicture}
\end{document}