pjv3 — PJv3 Self-Organizing Agents

pj_v3_complete_task destructive

v3 Hylomorphism FOLD operation: report task completion back to parent. The persona must have a parent in the hierarchy. Validates that all child delegation tasks are complete, then synthesizes results and creates an AgentMessage with message_semantic='fold_completion', carrying result data and optional child_results upward in the tree.

category

pjv3 (PJv3 Self-Organizing Agents)

permissions

agents.complete_task

Parameters

persona_id : string

UUID of the completing (child) persona

result_summary : string

Brief summary of the task result

child_results : array (optional)

Optional list of child result dicts [{persona_id, summary, status}] for synthesis

artifacts : array (optional)

Optional list of artifact dicts [{type, name, content}]

force : boolean (optional)

Force completion even if some child delegations are pending (use when retired/crashed children will never fold back)

pj_v3_delegate_task destructive

v3 Hylomorphism UNFOLD operation: delegate a task down the persona hierarchy. The sender must be a parent or ancestor of the target persona. Checks governance state and spawn_policy before delegating. Creates an AgentMessage with message_semantic='unfold_delegation', tree_path tracking, and refinement_context for progressive enrichment. Spawns an AgentInstance for the target if no active instance exists.

category

pjv3 (PJv3 Self-Organizing Agents)

permissions

agents.delegate_task

Parameters

persona_id : string

UUID of the sending (parent) persona

target_persona_id : string

UUID of the target (child) persona to delegate to

task_description : string

Description of the task to delegate

parent_message_id : string (optional)

Optional UUID of the parent delegation message (for multi-level chaining)

context : object (optional)

Optional refinement context dict passed to the child

session_id : string (optional)

Optional session ID for message flow isolation (auto-generated if omitted)

skip_governance : boolean (optional)

If true and caller is a root node (no parent), skip governance checks (state, spawn policy, oversight). Non-root callers: ignored. — default: false

resume_from_oversight : boolean (optional)

Internal: when true, skip ONLY the human-oversight gate (keeping budget/depth/ceiling checks) so an approved oversight request can re-execute the held delegation without re-holding. Set by the oversight-resume service, not by MCP callers. — default: false

pj_v3_escalate_task destructive

v3 Hylomorphism skip-level FOLD: escalate a task up the hierarchy. If target_persona_id is provided, the target must have higher or equal authority. If omitted, routes to the Lowest Common Ancestor (LCA) when a sibling context exists, or to the immediate parent. Creates an AgentMessage with message_semantic='fold_escalation'. Logs escalation with reason for audit trail.

category

pjv3 (PJv3 Self-Organizing Agents)

permissions

agents.escalate_task

Parameters

persona_id : string

UUID of the persona escalating the task

reason : string

Reason for escalation

target_persona_id : string (optional)

Optional UUID of the target persona to escalate to (must have >= authority). If omitted, routes to LCA or immediate parent.

skip_governance : boolean (optional)

If true and caller is a root node (no parent), skip governance checks (state, oversight). Non-root callers: ignored. — default: false

pj_v3_get_pool_stats destructive

Get session pool statistics for the organization. Returns counts of active, paused, and total instances, desktop agent availability, and capacity information.

category

pjv3 (PJv3 Self-Organizing Agents)

pj_v3_pause_session destructive

Pause an agent instance's session. Saves the current state (status, task, context) to metadata, marks the instance as paused, and frees browser resources. Use pj_v3_resume_session to restore.

category

pjv3 (PJv3 Self-Organizing Agents)

permissions

agents.pause_agent

Parameters

instance_id : string

UUID of the agent instance to pause

reason : string (optional)

Reason for pausing the session — default: ""

pj_v3_resume_session destructive

Resume a paused agent instance's session. Restores the instance to its pre-pause status and reactivates the HiveSession. The desktop agent will reconnect the browser.

category

pjv3 (PJv3 Self-Organizing Agents)

permissions

agents.resume_agent

Parameters

instance_id : string

UUID of the agent instance to resume

pj_v3_retire_agent destructive

Retire a PJ v3 agent instance permanently. Ends the associated HiveSession, marks the instance as retired, and frees all resources. Authority checks are enforced: the retiring agent must have a higher authority level or be self-retiring.

category

pjv3 (PJv3 Self-Organizing Agents)

permissions

agents.retire_agent

Parameters

instance_id : string

UUID of the agent instance to retire

reason : string

Reason for retiring this agent

retired_by_instance_id : string (optional)

UUID of the agent instance performing the retirement (for authority check)

force : boolean (optional)

Force retirement even if agent is working on a task — default: false

pj_v3_send_message destructive

Send a direct message between agent personas (v3 protocol). Validates communication permission (parent/child/sibling), checks governance state, and enforces rate limits. Uses semantic message types: unfold_delegation, fold_completion, fold_escalation, coordination, broadcast, heartbeat, status_update.

category

pjv3 (PJv3 Self-Organizing Agents)

permissions

agents.send_message

Parameters

sender_persona_id : string

UUID of the sending agent persona

target_persona_id : string

UUID of the receiving agent persona

content : object

Message content as a JSON object

message_semantic : string (optional)

Semantic message type: unfold_delegation, fold_completion, fold_escalation, coordination, broadcast, heartbeat, status_update — default: "status_update"

subject : string (optional)

Optional message subject line

session_id : string (optional)

Optional session UUID for message flow isolation

priority : integer (optional)

Message priority (1-10, default: 5) — default: 5

in_reply_to_id : string (optional)

UUID of the message this is replying to

metadata : object (optional)

Additional metadata

skip_governance : boolean (optional)

If true and caller is a root node (no parent), skip governance checks (communication permission, rate limit, content filter). Non-root callers: ignored. — default: false

pj_v3_spawn_agent destructive

Spawn a new PJ v3 agent instance from a persona template. Validates authority limits, creates the instance record, composes the full system prompt (persona + skills + hierarchy), and spawns a browser or terminal session on the desktop agent. Returns instance details and session information.

category

pjv3 (PJv3 Self-Organizing Agents)

permissions

agents.spawn_agent

Parameters

persona_id : string

UUID of the persona template to spawn from

browser_mode : string (optional)

Session type: 'desktop' for desktop browser, 'cloud' for cloud browser, 'terminal' for CLI session — default: "terminal"

spawn_reason : string

Reason for spawning this agent

parent_instance_id : string (optional)

UUID of the parent agent instance (for delegation chains). Child inherits session and workspace.

layout : string (optional)

Terminal layout: 'tab' (default), 'window' (separate window), 'hsplit' (side by side), 'vsplit' (top/bottom) — default: "tab" — enum: tab, window, hsplit, vsplit

split_from : string (optional)

Tab ID to split from (for hsplit/vsplit). Auto-selects latest pane if omitted.

initial_task : string (optional)

Optional task/mission to inject into the agent's system prompt. Appears as a '# Your Mission' section in CLAUDE.md so the agent begins working autonomously on startup.

desktop_agent_id : string (optional)

UUID or agent_id of a specific desktop agent to target. When multiple desktop agents are online, this ensures the spawn routes to the correct machine. If omitted, the most recently active agent is selected automatically.

mcp_endpoint : string (optional)

Override the MCP endpoint URL for this agent. Use '/api/mcp/pjv3/sse/' (restricted, coordination-only tools) to force delegation, or '/api/mcp/sse/' (full toolset) for worker agents. If omitted, auto-detected based on persona role.

allow_overage : boolean (optional)

Bypass instance and mission budget refusals. Use only when knowingly authorizing spend beyond the configured ceiling. — default: false

mission_id : string (optional)

UUID of the Mission to attach this instance to. When set, the instance's budget defaults to the mission's budget_usd (overriding the persona/org default). Used by pj_launch_mission's cloud-fallback path to propagate mission context to top-level spawns that have no parent instance.

on_behalf_of_tenant : string (optional)

OPERATOR-ONLY. Subdomain or UUID of a customer tenant to spawn this mission on behalf of, so it runs INSIDE that tenant's Studio container instead of the prod host. Binds the instance's human principal + organization to the target tenant (routing keys off them); the command stays owned by the operator's daemon. Refused unless the caller is a platform operator and the tenant has a READY studio.

on_behalf_of_user_id : string (optional)

Optional UUID of a specific active user in on_behalf_of_tenant to act as. When omitted, the tenant's default principal (internal operator, else first active admin) is used.