# Subagent Session Spawning Architecture and Lifecycle in Apache Maka

> Explore Apache Maka's subagent session spawning architecture and lifecycle. Learn how child sessions link to parents via SQLite and run in foreground mode under a shared Runtime Host.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: architecture
- Published: 2026-09-02

---

**Apache Maka creates subagent sessions through a three-structure metadata system that links child sessions to parents via durable SQLite storage, with all subagents currently running in foreground mode under a shared Runtime Host.**

Apache Maka's **subagent session spawning architecture** enables a parent session to delegate work to child sessions while maintaining full provenance and execution control. This article examines the complete lifecycle—from tool result generation through metadata persistence to session completion—based on the implementation in `apache/maka`.

## The Three Core Data Structures

Every subagent session is defined by three immutable data structures that travel together through Maka's storage and runtime layers. These structures encode the complete identity, lineage, and execution context of a child session.

### SubagentSessionParent

The `SubagentSessionParent` structure captures the parent-child relationship. It stores the `parentSessionId`, `parentRunId`, `parentTurnId`, optional **graph identifiers**, and **swarm context** that place the subagent within a larger computation graph.

### SubagentSessionRuntime

The `SubagentSessionRuntime` structure contains a snapshot of the child's execution environment. This includes the **agent ID**, **model prompt configuration**, **available tool list**, and **policy settings** that govern how the subagent operates.

### SubagentSessionSpawn

The `SubagentSessionSpawn` structure provides the immutable identity of the initial invocation. It holds the **request fingerprint** (for deduplication), **initial turn ID**, and **initial run ID** that mark the subagent's entry point.

These structures are defined in [`packages/core/src/session.ts`](https://github.com/apache/maka/blob/main/packages/core/src/session.ts) (line 90 defines the allowed `SUBAGENT_SESSION_LIFECYCLES`) and persisted to SQLite via [`packages/storage/src/sqlite-session-metadata-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-session-metadata-store.ts) in the `session_metadata` table columns `subagent_parent_*`, `subagentRuntime` (JSON), and `subagentSpawn` (JSON).

## Lifecycle Phase 1: Tool Result Generation

The subagent spawning process begins when a tool execution returns a specialized result type. A `ToolResultContent` with `kind: "subagent"` signals the Runtime Host that a child session should be created.

```ts
// A tool result that triggers subagent creation
const subagentResult: ToolResultContent = {
  kind: 'subagent',
  status: 'running',
  // Additional UI rendering fields handled by packages/ui/src/tool-activity.tsx
};

```

The UI layer in [`packages/ui/src/tool-activity.tsx`](https://github.com/apache/maka/blob/main/packages/ui/src/tool-activity.tsx) renders these results with appropriate visual indicators that distinguish subagent invocations from standard tool outputs.

## Lifecycle Phase 2: Session Provisioning

When the Runtime Host detects a subagent result, it delegates to `SessionManager.provisionSubagent` in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts). This method orchestrates the complete child session creation.

The provisioning flow performs three critical operations:

- **Child workspace construction** — creates an isolated execution context with resolved tool dependencies
- **Fresh ID generation** — allocates unique identifiers for the initial turn and run
- **Structure assembly** — builds the `SubagentSessionParent`, `SubagentSessionRuntime`, and `SubagentSessionSpawn` records (lines 915–224 in the provisioning request construction)

```ts
// SessionManager creates the child session with full provenance
const child = await sessionManager.provisionSubagent({
  source: {
    sessionId: parentId,
    runId: parentRunId,
    turnId: parentTurnId,
    toolCallId
  },
  graphId,      // Optional: graph context for swarm coordination
  workId,       // Optional: work unit identifier
  operatorId,   // Optional: executing operator reference
  // Preset configuration for model selection can also be provided
});

```

The resulting `child.header` contains all three subagent structures, ready for storage persistence.

## Lifecycle Phase 3: Metadata Persistence

The storage layer in [`packages/storage/src/sqlite-session-metadata-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-session-metadata-store.ts) enforces **idempotent child creation**. Before insertion, it validates that no existing record contains a `subagentSpawn` field for the target session (error thrown at lines 860–862).

```ts
// Storage layer validates and persists subagent metadata
const record = await store.readRecordSync(child.sessionId);
console.log(record.header.subagentParent?.parentSessionId);  // → parentId
console.log(record.header.subagentSpawn?.initialRunId);      // → first run id

```

The store uses `INSERT OR IGNORE` semantics to silently deduplicate attempts to recreate a child with the same `requestFingerprint`. This guarantees that network retries or duplicate tool results never spawn multiple orphaned sessions.

## Lifecycle Phase 4: Execution

Once persisted, the child session executes under the same **Runtime Host** as its parent. The host tracks progress through the standard turn/run pipeline:

- `AgentRun` orchestrates the agent's iterative execution loop
- `RuntimeKernel` manages tool invocations and state transitions

The child session operates with its own `subagentRuntime` configuration, allowing different models, prompts, or tool sets than the parent while remaining visible in the same UI column.

## Lifecycle Phase 5: Completion and UI Rendering

When the subagent finishes, its final status (`completed`, `failed`, or other terminal states) is recorded in durable storage. UI components such as [`packages/ui/src/titlebar-session-identity.tsx`](https://github.com/apache/maka/blob/main/packages/ui/src/titlebar-session-identity.tsx) retrieve the `subagentParent` data to render the complete parent-child trail, enabling users to navigate hierarchical session trees.

## Lifecycle Phase 6: Cleanup and Retention

Because all subagent metadata lives in SQLite, parent sessions can:

- Retrieve historic child runs for debugging or auditing
- Reconcile graph edges using stored `graphId` and `workId` references
- Retry the same spawn using the stored `requestFingerprint` (automatically deduplicated by the storage layer)

## Supported Lifecycle Modes

Apache Maka currently supports **only one lifecycle mode** for subagents:

| Mode | Behavior | Use Case |
|------|----------|----------|
| `foreground` | Child runs in same UI column as parent, visible to user | Interactive delegation, step-by-step workflows |

The `foreground` mode is defined in [`packages/core/src/session.ts`](https://github.com/apache/maka/blob/main/packages/core/src/session.ts) in `SUBAGENT_SESSION_LIFECYCLES` at line 90. Background or detached subagent execution is not yet implemented.

## Architectural Guarantees

The subagent spawning architecture provides three foundational properties:

- **Idempotent creation** — Duplicate `provisionSubagent` calls with identical fingerprints produce a single session via `INSERT OR IGNORE` in [`sqlite-session-metadata-store.ts`](https://github.com/apache/maka/blob/main/sqlite-session-metadata-store.ts)
- **Strong provenance** — Every subagent carries complete lineage including `parentSessionId`, `parentRunId`, `parentTurnId`, and optional swarm identifiers
- **Clean separation** — Core layer defines contracts, runtime layer orchestrates provisioning, storage layer handles persistence and lookup

## Summary

- Apache Maka subagents are created through a **three-structure metadata system** (`SubagentSessionParent`, `SubagentSessionRuntime`, `SubagentSessionSpawn`) defined in [`packages/core/src/session.ts`](https://github.com/apache/maka/blob/main/packages/core/src/session.ts)
- **Provisioning** happens via `SessionManager.provisionSubagent` in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts), which constructs child workspaces and allocates fresh IDs
- **Storage layer** enforces idempotency through fingerprint-based deduplication in [`packages/storage/src/sqlite-session-metadata-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-session-metadata-store.ts) (lines 860–862)
- All subagents run in **`foreground` lifecycle mode**, visible in the same UI column as their parents
- Complete **lineage and retry capability** is preserved through durable SQLite storage of parent references and request fingerprints

## Frequently Asked Questions

### What triggers a subagent session to spawn in Apache Maka?

A subagent spawns when any tool returns a `ToolResultContent` with `kind: "subagent"`. The Runtime Host detects this result type and invokes `SessionManager.provisionSubagent` to create the child session with full metadata linking it to the parent.

### How does Apache Maka prevent duplicate subagent creation?

The storage layer uses `INSERT OR IGNORE` semantics and validates that no `subagentSpawn` record exists before insertion (error at lines 860–862 of [`sqlite-session-metadata-store.ts`](https://github.com/apache/maka/blob/main/sqlite-session-metadata-store.ts)). The `requestFingerprint` in `SubagentSessionSpawn` serves as the deduplication key.

### Can subagents run in the background or detached from their parents?

No. Currently only the `foreground` lifecycle is supported, as defined by `SUBAGENT_SESSION_LIFECYCLES` in [`packages/core/src/session.ts`](https://github.com/apache/maka/blob/main/packages/core/src/session.ts) at line 90. Background subagents would require additional runtime and UI infrastructure not yet present in the codebase.

### Where is subagent metadata stored and how can it be inspected?

All metadata persists to SQLite in the `session_metadata` table: parent relationships in `subagent_parent_*` columns, runtime configuration in `subagentRuntime` (JSON), and spawn identity in `subagentSpawn` (JSON). Use `store.readRecordSync(sessionId)` to retrieve complete headers for inspection or parent-child navigation.