FACTUAL ACTIVITY RECORD · An activity record based on work that took place
Centralizing Custom Agent lifecycle control in Mako
Aligning work-boundary progress packets, depth-one launches, and Task completion checks across operations
Purpose
When multiple Custom Agents launched one another in a parent-child chain, ending an upstream agent could overlook active downstream work or a handoff that had not yet been collected. This happened during the Activity itself: the Organization Designer session was ended before its completion notice, leaving the final handoff unavailable.
Agent state and stop decisions needed to be centralized in Mako while domain leads retained ownership of requirements and ordering without operating the agent lifecycle. The work also addressed two operating risks: incomplete Task closure when one Pull Request covered multiple Tasks and accidental use of a Git helper from another repository through a relative path.
Implementation
AGENTS.md and .agents/skills/software-delivery/SKILL.md separated ownership: domain leads owned requirements, call order, start conditions, and join conditions, while Mako became the sole owner of Custom Agent lifecycle operations. Role agents could no longer directly spawn, message, interrupt, or close other agents; Mako launched every role directly below the root.
max_depth in .codex/config.toml changed from four to one, limiting Custom Agents to the root's direct children. Launches required a role ID, fork_context = false, and a minimal structured handoff packet; full-history context forks could not be combined with a Custom Agent role override. Continuing the same work used input and resume on the existing thread without changing its role.
Mako's active-agent ledger recorded the thread and role, requester, handoff sequence, running, waiting, completed, or error state, and active downstream work. A parent with active downstream work could not be treated as complete or stopped, and progress checks were limited to non-interrupting status requests. Forced-stop candidates were limited to nonresponse, an explicit runtime error or stop, and an explicit interruption from the CEO.
- The seven Custom Agents other than Mako returned packets at meaningful work boundaries—not on a time interval—including work start, requirements or Task creation, completion of design, drafting, implementation, or verification, role handoffs, review preparation, blockers, and final handoff.
- Each packet carried the current phase, completed work, running or waiting roles and Tasks, the work target, verification evidence, the next action, and blockers or risks.
- Receiving a packet did not itself mean completion or a stop. Mako checked active agents and downstream state before updating the aggregate status.
- Completion and final handoff recorded the work started, changes, verification, recorded artifacts, independent checks, and anything unfinished or blocked.
The progress packet and lifecycle boundary were synchronized beyond AGENTS.md into seven .codex/agents/*.toml definitions, the software-delivery and PR-review Skills, the review checklist, rules, hooks, setup, operating-model documentation, and handoff examples. During the work, the CEO replaced wording that could imply periodic reporting with reporting at meaningful work boundaries, and every surface was aligned to that definition.
.agents/skills/software-delivery/references/github-templates.md gained a Task-to-PR close manifest. The default remained one Task per Pull Request. When several Tasks shared one Pull Request, the body and handoff listed every primary, secondary, or supporting Task, its completion criteria, and its post-integration action. Mako compared the manifest with related Tasks before integration and afterward either completed every item or recorded the reason and next action for anything unresolved. A closing keyword was not treated as the completion ledger.
authentication helper and branch-push helper gained a check that compared the physical repository root derived from the script location with the Git top level being operated on. A mismatch stopped with exit code 2 before remote access. A match proceeded to authentication preflight and a live read of the remote default branch rather than a fixed branch name. The push helper called the authentication helper from the same directory while preserving protected-branch and non-force-push boundaries. The local package store was also added to tracking policy.
Verification parsed the project settings and seven agent definitions as TOML and confirmed max_threads = 12 and max_depth = 1. It also checked both shell scripts, rejection of a helper used from another repository and of a protected branch, authentication preflight, local Markdown links, residual wording for direct spawning, the new lifecycle, fork, and Task-completion policies, and git diff --check.
The following excerpt from .codex/config.toml was checked line by line against the primary Commit diff at the cutoff.
[agents]
# Global cap for concurrently open custom-agent threads; static agent definitions do not consume slots.
# If all seven current roles run one instance each, 12 leaves capacity for five additional concurrent threads.
max_threads = 12
# Mako is the only agent lifecycle owner; every custom role runs directly under root depth 0.
max_depth = 1
job_max_runtime_seconds = 1800Rendering diagram…
What was confirmed
Verification results
The final change covered 28 files with 346 additions and 98 deletions. Centralized lifecycle control, depth-one launches, work-boundary progress packets for seven roles, Task completion checks, and the repository-local helper boundary agreed across configuration, agent definitions, Skills, rules, hooks, templates, and operating documentation.
The Organization Designer whose final handoff had been lost after an early stop was resumed in the same role and session at the CEO's direction instead of being replaced by a new session. Later, the running reviewer was not treated as complete merely because time had passed; the workflow waited for an explicit result.
TOML parsing, shell syntax, repository-identity rejection, protected-branch rejection, authentication preflight, links, policy residual searches, and the patch check succeeded.
Verification did not perform an actual push. The restriction on combining fork_context with a role override could not be confirmed directly from public references and was therefore treated as project policy. The Activity did not exercise every runtime interruption condition or every multi-Task path.
Basis for completion
The Activity was complete when Custom Agent lifecycle control, work-boundary progress packets, Task completion checks, and repository-local helper boundaries were consistent across 28 files, and static checks of the settings, documentation, template, and helpers succeeded.