ccpe-system/runtimes/hybrid/agent-invocation-packet.protocol.md

artifact_type	name	protocol_id	author	version	created	updated	status	target_platform	based_on	related_runtimes
ccpe-runtime-subprotocol	agent-invocation-packet	agent-invocation-packet	CCPE System	0.3.0	2026-06-06	2026-06-07	draft	Codex / Claude Code / OpenClaw / GPT / Gemini / Claude / manual workflow	CCPE System	viewpoint-discussion-distillation article-outline-development

Agent Invocation Packet Protocol

1. Purpose

Define how a Runtime launches, delegates to, or hands off work to a canonical CCPE participant.

This protocol prevents a runtime operator from accidentally simulating an Agent, Skill, Runtime node, or native platform participant and labeling the result as a formal participant output.

2. Scope

Use this protocol whenever a workflow needs to invoke:

- CCPE-Lite prompt
- CCPE-Agent spec
- CCPE-Skill spec
- CCPE-Runtime node
- native platform agent
- external GPT / Gemini / Claude participant
- manual human-run participant
- main-session synthesis over returned participant outputs

For viewpoint-discussion-distillation, this includes:

- whole-source-gestalt-reviewer
- topic-discovery-router
- topic-graph-synthesizer
- lossless-coverage-auditor
- conversation-segmentation
- evidence-routing-and-topic-doc-builder

3. Required Files

For every participant invocation, create or record:

agent-invocation-packet.md

When the participant runs outside the local runtime or cannot read local CCPE files, also create:

prompt-to-send.md

For task-specific context, create when needed:

dispatch-pack.md

For every formal participant output, save:

returned-output.md

If the runtime operator directly executes a CCPE Skill inside the current session, the operator must still write:

skill-execution-record.md

The record must identify the Skill spec path, task input, files read, files written, procedure steps completed, validation checks, and skipped or failed steps.

4. Invocation Modes

full_prompt_paste:
  Use when the participant runs in GPT, Gemini, Claude, or another external platform that cannot read local files.
  prompt-to-send.md must contain the canonical prompt/spec, current task, context files or embedded context, and output contract.

prompt_path_reference:
  Use when the executing agent can read local files.
  The invocation packet may reference the canonical artifact path, but must still include task, input files, output contract, continuity policy, and proof that the participant can read the referenced path.
  This mode requires a real executing participant distinct from the runtime operator role. The main runtime session may not simply read the referenced spec and label its own output as that participant's formal output.

native_agent_id:
  Use when the platform has a registered agent with matching role and version.
  The invocation packet must still record target agent, task, context, output contract, carrier metadata, and session logging rules.

local_skill_execution:
  Use when the runtime operator can faithfully execute a CCPE-Skill spec in the current session.
  A skill-execution-record.md is required. The output must be labeled as Skill execution, not Agent judgment.

manual_handoff:
  Use when the user will run the participant manually.
  The packet must be sufficient for copy-paste execution and return-path recording.

main_session_synthesis:
  Use only when the runtime operator mechanically integrates already-returned participant outputs.
  This is not a participant judgment. It cannot replace Agent output, Skill execution, or external participant return.

4.1 Carrier Types

Every invocation or synthesis record must declare a carrier type:

codex_thread_participant:
  A separate Codex thread or sub-session that can preserve participant role, read required files, and return output.

agent_subsession_participant:
  A platform-provided subagent or worker session with a distinct participant boundary.

local_skill_execution:
  The current session executes a CCPE-Skill spec and writes a skill-execution-record.md.

external_manual_participant:
  A human or external platform runs prompt-to-send.md and returns output.

main_session_synthesis:
  The main runtime session integrates returned outputs without pretending to be a formal participant.

4.2 Strict Invocation Profile

Strict invocation is required by default for:

- production runs
- tests
- audits
- downstream handoffs
- source-heavy extraction
- formal topic graph synthesis
- participant outputs that will affect user decisions

Strict invocation requires:

- agent-invocation-packet.md or skill-execution-record.md
- carrier metadata
- execution_status: returned
- returned-output.md for Agent / Runtime node / external / manual participants
- Skill execution record for local Skill execution
- clear simulation_only value
- runtime acceptance rule satisfied

If strict invocation is required and evidence is incomplete, the valid state is:

blocked_waiting_for_participant_output

4.3 Real Participant Test

Before a Runtime accepts a participant output, at least one condition must be true:

- The participant ran in a separate agent/session/thread with the canonical artifact loaded or pasted.
- The participant ran as a native platform agent with a matching registered identity.
- The participant ran externally through prompt-to-send.md and returned output was saved.
- The task was a CCPE-Skill executed locally with a Skill execution record.
- The user manually ran the participant and returned the output with source metadata.

The following is not a real participant invocation:

- The runtime operator reads an Agent spec and writes what the Agent "would have said".
- The main session produces an Agent report without a participant startup packet and returned output.
- A locator-only source map is treated as sufficient source content for a judgment Agent.
- An agent-invocation-packet.md exists but was never sent to or executed by a participant.
- A prompt-to-send.md exists but has no returned output.
- A canonical artifact path is referenced but the record does not prove the participant could read it.

4.4 Persistent Carrier Rule

Some stages require a participant carrier that can continue after human correction.

Persistent carrier is required when:

- the participant establishes a lens that workers will use later
- user correction may require the same participant to revise or clarify
- the output becomes a binding alignment record
- a Runtime stage needs follow-up without losing participant identity

For viewpoint-discussion-distillation, Step 0 Whole-Source Gestalt Alignment requires persistent carrier when user correction may be needed. A one-shot output may be useful reference analysis, but it is not a valid formal persistent-alignment record if the carrier cannot resume after correction.

5. Agent Invocation Packet Format

# Agent Invocation Packet: {participant_id}

## 1. Invocation Identity

- project_id:
- workflow:
- stage:
- run_id:
- participant_id:
- target_participant_name:
- participant_type: ccpe_lite | ccpe_agent | ccpe_skill | ccpe_runtime_node | native_agent | external_agent | human | main_session_synthesis
- canonical_artifact_path:
- canonical_artifact_version:
- invocation_mode: full_prompt_paste | prompt_path_reference | native_agent_id | local_skill_execution | manual_handoff | main_session_synthesis
- packet_type: orchestrator_index | participant_startup_packet | skill_execution_record | synthesis_record

## 2. Carrier Metadata

- carrier_type: codex_thread_participant | agent_subsession_participant | local_skill_execution | external_manual_participant | main_session_synthesis
- thread_id:
- agent_id:
- persistent_required: true/false
- resume_or_followup_method:
- execution_status: prepared | sent | returned | blocked | failed | simulation_only
- strict_invocation_required: true/false
- simulation_only: true/false
- returned_output_path:
- skill_execution_record_path:
- prompt_to_send_path:

## 3. Canonical Artifact Handling

- should_paste_full_prompt_or_spec: yes/no
- role_integrity_requirement:
- allowed_wrapper_instructions:
- forbidden_role_changes:
- no_simulation_requirement:
- path_readability_evidence:

## 4. Current Task

## 5. Input Files

## 6. Context Files

## 7. Embedded Inputs

## 8. Output Contract

- source_primary_language:
- output_language_policy: mirror_source_primary_language | user_specified | protocol_default
- human_review_language_requirement:
- human_confirmation_artifact: true/false
- gate_id_if_applicable:

## 9. Continuity Policy

## 10. Session Logging

## 11. Forbidden Actions

## 12. Return Path

## 13. Runtime Acceptance Rule

6. Prompt To Send Format

# Prompt To Send: {participant_id}

## 1. Canonical Agent Prompt Or Spec

Paste the canonical CCPE prompt/spec here when invocation_mode = full_prompt_paste or when the external participant cannot read local paths.

## 2. Runtime Wrapper

You are being invoked for one stage of a larger workflow. Preserve your canonical role and follow the task below.

## 3. Carrier Metadata To Return

- participant_id:
- carrier_type:
- external_session_id:
- persistent_available:
- source_material_received:
- canonical_artifact_received:
- source_primary_language:
- output_language_policy:
- human_review_language_used:

## 4. Current Task

## 5. Project Context

## 6. Input Files Or Embedded Inputs

## 7. Context Pack

## 8. Output Requirements

Include the requested output language policy. For any human-confirmation artifact, Gate-facing output, or returned output likely to be reviewed by the user, use the source material's primary language as the dominant language unless the invocation explicitly says otherwise.

## 9. Session Continuity Instructions

## 10. Return Instructions

7. Returned Output Format

# Returned Output: {participant_id}

## 1. Return Metadata

- project_id:
- workflow:
- stage:
- run_id:
- participant_id:
- participant_type:
- canonical_artifact_path_or_pasted_spec:
- canonical_artifact_version:
- invocation_mode:
- carrier_type:
- thread_id:
- agent_id:
- persistent_available:
- execution_status: returned
- simulation_only: false
- source_primary_language:
- output_language_policy:
- human_review_language_used:
- human_confirmation_artifact:
- gate_id_if_applicable:

## 2. Inputs Actually Received

## 3. Files Or Source Material Actually Read

## 4. Participant Output

## 5. Confidence And Limits

## 6. Follow-Up / Resume Instructions

The runtime operator may wrap or index returned output, but must not alter the participant's substantive result without labeling the change as main-session integration.

8. Skill Execution Record Format

# Skill Execution Record: {skill_id}

## 1. Skill Identity

- skill_id:
- canonical_skill_path:
- skill_version:
- execution_mode: local_skill_execution
- carrier_type: local_skill_execution
- strict_invocation_required:
- simulation_only: false

## 2. Task Input

## 3. Files Read

## 4. Files Written

## 5. Procedure Steps Completed

## 6. Validation Checks

## 7. Skipped Or Failed Steps

## 8. Output Summary

## 9. Return Path

9. No Simulation Rule

The runtime operator may:

- prepare files
- generate invocation packets
- generate prompt-to-send.md
- execute a CCPE Skill locally when the Skill spec is explicit and a skill-execution-record is written
- collect real participant outputs
- mechanically integrate real returned outputs
- ask the user for decisions

The runtime operator must not:

- write a formal Agent report as if it came from a canonical Agent
- write a Skill result without recording the Skill spec and execution record
- write a downstream task packet as if a router, synthesizer, or auditor approved it when that participant was not invoked
- include simulation-only outputs in formal synthesis or audit
- use its own convenience summary as a canonical participant output
- treat packet-only or prompt-to-send-only files as execution evidence

If real invocation is unavailable, the operator must stop after generating the invocation packet and mark:

blocked_waiting_for_participant_output

Simulation outputs, if explicitly requested by the user, must be labeled:

simulation-only
excluded-from-synthesis
not-a-formal-report

10. Packet-Only And Prompt-Only Invalidity Rule

packet-only is not execution.
prompt-to-send-only is not execution.
canonical artifact path reference is not execution.
main-session role approximation is not execution.
polished output is not evidence of valid invocation.

A Runtime may prepare packet-only or prompt-only files as a blocked handoff state, but it must not accept them as participant output.

11. Viewpoint Runtime Default Canonical Paths

whole-source-gestalt-reviewer: agents/agent-specs/whole-source-gestalt-reviewer.agent.md
topic-discovery-router: agents/agent-specs/topic-discovery-router.agent.md
topic-graph-synthesizer: agents/agent-specs/topic-graph-synthesizer.agent.md
lossless-coverage-auditor: agents/agent-specs/lossless-coverage-auditor.agent.md
conversation-segmentation: skills/workflow/conversation-segmentation.skill.md
evidence-routing-and-topic-doc-builder: skills/workflow/evidence-routing-and-topic-doc-builder.skill.md
viewpoint-discussion-distillation: runtimes/hybrid/viewpoint-discussion-distillation.runtime.md

12. Validation Checklist

Participant identified?
Canonical artifact path present or full spec pasted?
Invocation mode explicit?
Carrier type explicit?
Persistent requirement explicit?
Strict invocation requirement explicit?
Simulation-only status explicit?
Prompt-to-send generated when needed?
Task separated from canonical role?
Output contract present?
Output language policy present when human review is required?
Human-confirmation artifact flag present when the output enters a Gate?
Session logging path present?
Return path present?
Returned-output.md present for Agent / Runtime node / external / manual participant?
Skill execution record present when local_skill_execution is used?
Path readability evidence present when prompt_path_reference is used?
No simulation mislabeled as formal output?
Packet-only rejected as execution?
Prompt-to-send-only rejected as execution?
Runtime acceptance rule explicit?

13. Runtime Acceptance Rule

A Runtime may accept a participant output only when one of the following is true:

- a completed participant_startup_packet was executed by a real participant and returned-output.md was saved
- a prompt-to-send.md was run externally and returned-output.md was saved with source metadata
- a native platform agent ran under matching identity and returned-output.md was saved
- a local_skill_execution record shows the Skill spec was executed and validated
- the user explicitly labels the material as simulation-only and the Runtime excludes it from formal synthesis

If none of these is true, the Runtime must treat the stage as blocked.

14. Version Notes

v0.3.0:
- Added carrier metadata, strict invocation profile, persistent carrier rule, returned-output.md format, packet-only invalidity, prompt-to-send-only invalidity, and main-session synthesis boundary.

v0.2.0:
- Added real participant test, prompt-to-send handling, Skill execution record, and no-simulation rule.