+// CreateChild writes a new direct child with its own ID and the model, effort,
+// and working directory of the root. Child and subagent names share a
+// namespace. The config is complete before an atomic rename publishes the
+// child. Preparation stays outside children, so an interrupted write cannot
+// stop startup.
+func (a *Agent) CreateChild(name, responsibility string, subagents *Subagents) (_ *Agent, err error) {
+ if a.config.Parent != "" {
+ return nil, errors.New("only the root can create children")
+ }
+
+ if !agentChildNameValid(name) {
+ return nil, errors.New("name must have 2 to 32 ASCII letters and start with a capital letter")
+ }
+
+ if name == a.config.Name {
+ return nil, errors.New("the name is already used by the root")
+ }
+
+ responsibility = strings.TrimSpace(responsibility)
+ if responsibility == "" {
+ return nil, errors.New("responsibility must not be empty")
+ }
+
+ err = subagents.Reserve(name)
+ if err != nil {
+ return nil, fmt.Errorf("reserve child name: %w", err)
+ }
+
+ published := false
+ defer func() {
+ if !published {
+ subagents.Release(name)
+ }
+ }()
+
+ staged, err := os.MkdirTemp(a.dir, ".child-*")
+ if err != nil {
+ return nil, fmt.Errorf("prepare child directory: %w", err)
+ }
+
+ defer func() {
+ cleanupErr := os.RemoveAll(staged)
+ if cleanupErr != nil {
+ err = errors.Join(err, fmt.Errorf("remove prepared child: %w", cleanupErr))
+ }
+ }()
+
+ config := a.config
+ config.Name = name
+ config.ID = ""
+ config.Parent = a.config.Name
+ config.Responsibility = responsibility
+ child, err := writeAgent(staged, config)
+ if err != nil {
+ return nil, fmt.Errorf("write child: %w", err)
+ }
+
+ dir := filepath.Join(a.dir, "children")
+ err = os.MkdirAll(dir, 0o700)
+ if err != nil {
+ return nil, fmt.Errorf("create children directory: %w", err)
+ }
+
+ dir = filepath.Join(dir, name)
+ err = unix.Renameat2(unix.AT_FDCWD, staged, unix.AT_FDCWD, dir, unix.RENAME_NOREPLACE)
+ if err != nil {
+ return nil, fmt.Errorf("publish child directory: %w", err)
+ }
+
+ published = true
+ child.dir = dir
+
+ return child, nil
+}
+