Đệ Đệ (pi-dede)

Give the main Pi agent a small team, not another orchestration problem.

delegate_to_subagents runs one to three bounded tasks in parallel. The main agent owns the plan and final decision. Children return evidence or an approved change, with cost, timing, evidence status, and recovery information.

Start with a quick scout

{
  "objective": "Find the token-expiry invariant needed for the fix",
  "sharedContext": "Start in src/auth. Preserve TokenStore's public interface.",
  "agents": [{
    "id": "expiry",
    "profile": "scout",
    "effort": "quick",
    "goal": "Trace token expiry in src/auth and its direct tests. Return the invariant and up to three exact path/symbol/line excerpts. No edits. Stop when the behavior is established."
  }]
}

quick selects isolated context, low thinking, and a 60-second execution deadline. It uses the configured profile model, or the main model when no profile model is configured. It does not guess which provider is cheaper.

Use direct tools for a known read or command. Delegate when a bounded multi-step task saves main-agent work, context, or waiting time. A project map can be enough to define an early scout; reading the implementation first is not required.

Effort

agents[].effort	Default context	Thinking fallback	Execution deadline
quick	isolated	low	120s
standard or omitted	auto	profile default	180s
deep	auto	high	300s

Explicit context, model, thinking, and timeout fields override preset defaults. Configured profile thinking overrides the preset thinking fallback. Forked children keep the main model for cache compatibility. Isolated children, including auto fallbacks, use the configured profile model unless model is explicit.

No routing-model call, automatic model escalation, or extension-level retry is added. Pi/provider retry and compaction behavior remain host-controlled. Queue, setup, and cleanup time are additional to the execution deadline. Quick runs do not ask the user to extend their deadline.

Useful handoffs, small context

Each child receives a bounded contract: outcome, scope, required evidence, constraints, and stop condition. Read-only children report answered, partial, or blocked under an opening ## Status.

Results distinguish runtime success from child-reported evidence completeness. Missing or malformed status is unreported, not an inferred success. The main agent still verifies important claims and worker diffs.

Model-facing output includes model, turns, elapsed time, reported cost, recovery handles, and a full-output retrieval route. Exact per-section allocation keeps every child's metadata inside 4 KiB / 160 lines and the run inside 12 KiB / 500 lines. An artifact does not mean the displayed answer was truncated. Full answers and persistent JSONL sessions remain available through the stated routes; temporary artifacts expire at main-session shutdown.

Profiles and capabilities

Profile	Default tools	Standard thinking	Assignment
scout	read-only	low	Locate and extract decisive code evidence
reviewer	read-only	medium	Check one contract or risk
debugger	read-only	medium	Establish one root cause; do not fix it
security	read-only	medium	Trace one trust boundary
tester	coding	medium	Run checks or write approved tests
documenter	coding	low	Update approved documentation
worker	coding	medium	Implement an approved plan
custom	read-only	low	One caller-defined specialty

Read-only tools: read, grep, find, ls. Coding adds bash, edit, write. toolPreset can be read-only, coding, none, or custom; an explicit tools array selects the exact custom set.

Any bash, edit, or write capability consumes the sole writer slot, including command-only validation. Writers serialize across concurrent calls. Read-only siblings must not depend on unfinished edits. The lease coordinates pi-dede children, not the main agent or external editors. Recursive delegation is blocked.

Context and reuse

• isolated: new conversation, selected tools, concise supplied context. Quick's default. Pass relevant trusted rules in sharedContext.
• auto: reuse a safe main-session prefix when model, ordered tool metadata, and context economics permit; otherwise report the reason for isolation. No transcript scan is needed for explicitly isolated or continued children.
• fork: require a compatible prefix; fail before launch if unavailable. Exclude the unresolved delegation tool call.

Auto defaults to a 4,000-token minimum and a 70% context-window ceiling. Forks preserve visible tool metadata while enforcing the allowed executable subset. Provider/context hooks are not fully observable, so cache reuse is best-effort, not guaranteed. No inherited in-memory extension state is assumed.

A successful child returns continuationHandle. For directly related work:

{
  "objective": "Check the related caller using established evidence",
  "sharedContext": "The main agent verified the previous finding. Current change: ...",
  "agents": [{
    "id": "caller",
    "continueFrom": "<continuationHandle>",
    "goal": "Re-read the affected caller and establish whether it preserves the invariant. Return exact evidence and stop."
  }]
}

A timeout may return resumeHandle. Use resume in a solo call only when partial evidence shows little remains; default 60s, allowed 30–180s. Do not resume blindly.

Both workflows retain the same persistent session and immutable profile, model, thinking, tools, environment, and effort. Only id, goal, and timeout change. A continuation uses its original effort's timeout default. Raw session IDs are not capabilities.

Handles are atomically claimed. Successful handles expire after 30 idle minutes and only the 12 most recent successful lineages remain available. Shutdown, reload, or session replacement clears all handles, not the persistent conversations.

Configuration

Configure a cheaper model you have access to in ~/.pi/agent/pi-dede.json, or .pi/pi-dede.json in a trusted project:

{
  "profiles": {
    "scout": { "model": "anthropic/claude-haiku-4-5", "thinking": "low" },
    "worker": { "thinking": "medium" }
  },
  "context": { "forkMinTokens": 4000, "forkMaxContextRatio": 0.7 }
}

Configuration is read on each delegation. Project fields override global profile fields; environment maps merge by name. Per-agent fields override configuration. Profile models apply whenever a child runs isolated, including quick's default and auto fallbacks. A successful auto/fork keeps the main model.

Trusted additionalArgs is a flag/value object, for example { "-e": "/absolute/provider-extension.ts", "--fast": true }. A profile-level object replaces the shared object, including {}. true emits a flag, false omits it, and a non-empty string emits a flag/value pair. Any extra arguments force auto isolation because their effect on fork fidelity is unknown. Conflicting lifecycle flags are the configuration owner's responsibility.

Profile and per-agent env overrides accept portable names and string values. The merged map is limited to 64 variables / 16 KiB, with 8 KiB per value. Startup, session, and delegation controls are protected. Per-agent values are stored in the main transcript; do not pass secrets there.

Install and check

pi install npm:@khanhicetea/pi-dede
# Local checkout:
pi install /absolute/path/to/pi-kit/packages/pi-dede
# From this repository:
npm run check --workspace @khanhicetea/pi-dede

Reload Pi after updating. Load /skill:subagents for orchestration rules and examples.

Safety and limits

Children use headless pi --mode rpc, private prompt files, and task delivery over stdin. They retain OS permissions and inherited environment: this is not a sandbox. Normal global resources can affect isolated children. Project trust follows Pi and the built-in --no-approve flag unless trusted extra arguments override it. Forks disclose the selected main conversation to the model.

At a soft deadline, the child receives a finalize warning. Hard timeout and cancellation clear queued steering, abort, then clean up the process tree. Failed cleanup quarantines the runtime. Prompts use private temporary directories; child sessions remain in Pi's session storage. Cancellation evidence is persisted, but thrown cancellation cannot contribute nested usage to Pi's normal tool totals.

Input UTF-8 limits: objective 4 KiB; shared context 16 KiB; system prompt 8 KiB. Normal deadlines accept 30–1800 seconds. Structured child text is capped at 32 KiB; larger output uses artifacts.

Existing calls retain standard defaults. Structured details remain version 2, with optional evidence fields. See SPEC.md and IMPLEMENTATION-NOTES.md. Local tests do not establish real-provider speed or cost savings, or a supported-version/platform matrix.