RFC: Persistent work threads with bounded command dispatch

[pikos-apikos]

RFC: Persistent Work Threads with Bounded Command Dispatch

Summary

Add a native orchestration primitive that lets a parent Codex agent create a
persistent child work thread and resume it with one bounded command at a time.

The parent owns the global plan. Each child thread owns the accumulated local
context of one responsibility. The child performs only the current command,
returns a structured result, and becomes idle until resumed.

create_work_thread(role, context_policy) -> thread_id
send_command(thread_id, bounded_command) -> command_id
inspect_thread(thread_id)
compact_thread(thread_id)
close_thread(thread_id)

Problem

Current sub-agent delegation is optimized for self-contained tasks. This works
well for parallel jobs, but it is a poor fit for work that benefits from a
long-lived specialist context:

1. inspect one subsystem;
2. report findings;
3. receive a precise change request;
4. implement only that change;
5. receive a focused test request;
6. respond to review feedback in the same context.

Today the parent must either:

• send a large task and surrender too much planning authority to the child;
• create fresh children and repeatedly reconstruct context; or
• approximate continuity through files and oversized prompts.

The missing abstraction is not another autonomous agent. It is a supervised,
reusable work thread.

Proposed Semantics

Parent responsibilities

The parent retains:

• the user goal and complete backlog;
• dependency ordering;
• thread selection;
• conflict resolution;
• integration and final verification;
• the decision to resume, compact, or close a thread.

Child-thread responsibilities

A child work thread has:

• a stable thread_id;
• a role and optional model/tool/file policy;
• accumulated conversational context;
• zero or one active command;
• an idle, running, blocked, compacted, or closed state;
• a bounded command history and durable checkpoint.

The child executes only the current command. It must not infer and perform
future backlog items.

Suggested API

type WorkThreadState =
  | "idle"
  | "running"
  | "blocked"
  | "compacted"
  | "closed";

type WorkCommand = {
  objective: string;
  scope?: string[];
  constraints?: string[];
  context_refs?: string[];
  expected_result?: string;
};

type CommandResult = {
  status: "completed" | "blocked" | "failed";
  summary: string;
  files_read?: string[];
  files_changed?: string[];
  validation?: string[];
  discoveries?: string[];
  blocker?: string;
  ready_for_next: boolean;
};

create_work_thread({
  role,
  model?,
  tool_policy?,
  file_scope?,
  context_policy?
}) -> { thread_id }

send_command(thread_id, command: WorkCommand)
  -> { command_id }

inspect_thread(thread_id)
  -> { state, active_command?, last_result?, checkpoint? }

compact_thread(thread_id, checkpoint?)
  -> { state: "compacted", checkpoint }

close_thread(thread_id)
  -> { state: "closed" }

send_command should reject concurrent execution on the same thread. A later
version may support a small explicit queue, but implicit unbounded queuing
should not be the default.

Example

parent:
  create thread "grid-contract" with write scope src/grid/**

command 1:
  Read the current query/grid contract and report its invariants.

result 1:
  Four invariants found; no files changed; ready for next.

command 2:
  Add only the three requested fields while preserving those invariants.

result 2:
  Two files changed; focused typecheck passes; ready for next.

command 3:
  Add focused contract tests for the new fields.

The parent never needs to send the entire future backlog. The child does not
need to rediscover the subsystem between commands.

Why This Is Different from Session Reuse

Session reuse is the storage mechanism. Persistent work threads add explicit
orchestration semantics:

• stable identity and lifecycle;
• single-command discipline;
• parent-owned backlog;
• inspectable state;
• bounded context and checkpointing;
• policy inheritance;
• structured results;
• safe compaction and closure.

Context and Security

The API should accept a context_policy even if the first implementation only
supports a small subset. This creates a path toward:

• minimum-context disclosure;
• provider/model-specific routing;
• file and tool boundaries;
• provenance of injected context;
• auditable disclosure records.

The immediate feature does not require a personal memory graph or cross-provider
broker. It only needs to avoid baking in the assumption that every child sees
the complete parent context.

Compatibility

This should complement normal task delegation:

• spawn_task(...): autonomous, self-contained job;
• create_work_thread(...) + send_command(...): supervised, continuous work.

Existing task behavior should remain unchanged.

Acceptance Criteria

1. A parent creates a child thread and receives a stable identifier.
2. The parent sends a bounded command and receives a structured result.
3. After completion, the same thread can be resumed without reconstructing its
   prior conversational context.
4. A running thread cannot execute a second command concurrently.
5. The child stops after the current command.
6. The parent can inspect state and the last result.
7. The thread can be compacted into a durable checkpoint and resumed.
8. The thread can be closed explicitly.
9. Tool/file/model policy remains attached across resumptions.
10. Existing self-contained sub-agent tasks continue to work.

Request

Would the Codex team be open to this orchestration primitive and its lifecycle
semantics? If the direction is acceptable, I would be happy to turn the design
into a scoped implementation plan or contribute code in the repository's
preferred workflow.

[github-actions]

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• Codex Desktop regression: Subagents panel no longer opens a writable child-agent chat #34591
• Preserve and resume the full subagent tree when resuming a paused main agent thread #35368

Powered by Codex Action

[pikos-apikos]

Thanks for the duplicate pointers. I reviewed #34591 and #35368. They are related at the mechanism level (writable/resumable subagents), but this RFC proposes an additional orchestration semantic:

• the parent owns the global plan and undisclosed backlog;
• a persistent specialist receives exactly one bounded command per dispatch;
• the specialist's identity, policy, and local context survive across commands;
• every command ends with a structured result and an idle boundary;
• inspect, compact, and close are explicit lifecycle operations.

In short: resumption is the mechanism; parent-owned bounded command dispatch is the supervision contract. This can build on the capabilities proposed in those issues rather than replace them.

There is also a testable inference-economics hypothesis worth making explicit. Disposable agents repeatedly reconstruct subsystem context. A bounded persistent specialist can instead reuse a stable cached prefix, compact active history, and retrieve only relevant prior observations. Idle threads require storage rather than inference.

This is not automatically cheaper: without prefix caching and compaction, a growing transcript may cost more than fresh agents. A useful benchmark would compare equivalent workflows across:

1. fresh self-contained agents;
2. persistent threads without compaction;
3. persistent threads with prefix caching and bounded checkpoints.

The implementation should expose cached/uncached input tokens, output/reasoning tokens, compaction frequency, retries, duplicated exploration, and rework. The success criterion is not merely continuity; it is whether Codex can scale retained specialist knowledge without scaling continuously active inference.