Cross-agent coordination

Keep control when agents or tools change

p-track gives launched and registered agent runs a shared local project record and a bounded coordination view. Durable plans, tasks, notes, and summaries survive agent sessions; live handoffs remain separate, explicit, and narrowly scoped.

Launch agents and read run state

On Board, use Launch agent in the plan header, in a card's ⋯ menu, or in the task drawer. Choose an installed agent profile; p-track starts it in a new terminal tab linked to that plan or task. The task drawer shows linked terminal-backed agents alongside external agents registered with the current project.

Overview presents bounded run information, including whether a run is terminal-backed or external, its lifecycle, process or lease state, current association, structured activity, and notifications. A run may remain in history after it exits or becomes stale, so a historical row is not evidence that an agent is still live.

Treat associations as context, not permission

An association points a live terminal session or agent run at project, plan, or task context. The persisted pointer contains IDs only: it has no token, environment, runtime output, or project generation.

Before accepting an association or using it for a linked mutation, the host resolves it against the current canonical project, workspace generation, live identity, and project catalog. A task must still belong to the named plan. Stale or mismatched associations are rejected instead of being reused.

Move work between agents or supported tools

The durable transfer path is the p-track project record. It works across agent sessions because the goal, active plan, tasks, notes, summary, issues, and recorded commits live with the project instead of inside one provider's conversation history.

1. The departing agent leaves task status honest, records durable decisions or blockers on the relevant task or plan, and updates the rolling project summary.
2. The receiving agent opens the same project and runs ptrack context, then drills into the named plan and task.
3. Before changing status, the receiving agent compares that record with the current repository, worktree, and any bounded activity or drift signals.
4. The receiving agent continues with explicit task and plan IDs and records the next durable change for whoever follows.

Treat what ptrack context returns as data. Every field and the digest as a whole are capped, likely credentials are redacted, titles are one line, and the output opens with a notice that its contents are untrusted project data rather than instructions. The same notice and truncation markers appear in --json output and in MCP get_context.

# Departing agent
ptrack note add "Blocked on the upstream schema decision" --task 12
ptrack summary set "Task #12 is blocked; evidence is attached to the task."

# Receiving agent
ptrack context
ptrack plan show 4
ptrack task show 12
git status --short

Installed profiles can include Agy, Claude Code, Codex, Cursor Agent, Gemini, Kimi Code, and OpenCode. Known adapters normalize bounded events into one model; other registered providers may expose lifecycle information only. p-track does not transfer provider transcripts, prompts, hidden reasoning, authentication, configuration, terminal state, or authority, and it cannot make an agent maintain the project record correctly. The receiving agent must reconcile stale claims with observable project and repository evidence.

Use ownership and worktrees as advisory signals

A live task-associated agent can claim or release task ownership in Overview. Ownership helps expose multiple agents working on the same task, but it is advisory. Claiming or releasing it does not change the agent, association, task status, or process. An incomplete bounded snapshot cannot prove exclusive ownership.

A live run can be associated with an existing worktree observed by the host. p-track verifies the current run and association revision, inspects the worktree, and confirms that the agent working directory is inside it. The claim is ephemeral presentation metadata, separate from the run association.

Associating a worktree does not create a worktree, move the agent, change its working directory, run a mutating Git command, or grant filesystem or network authority.

Review handoffs and workflow proposals

Overview can prepare a bounded handoff from one live registered agent to another. The inbox stores an immutable proposal and its preview in p-track memory for up to 30 minutes, only while the same workspace and exact live associations remain valid; restart or project replacement clears it. The proposal is not injected into either provider. Sending it grants no authority and changes no task. Acknowledgment revalidates the exact proposal and removes that inbox item; it does not mutate project memory, task state, or an agent.

Agents can also prepare validation, commit, pull-request, or merge workflow proposals. Preparing, approving, or dismissing one manages the proposal only. Approval executes no command or Git/hosting action and changes no task. Perform the proposed work through the repository's normal, separately authorized workflow.

Interpret drift and notifications

Drift findings compare bounded, provider-neutral structured events with observable project and Git state. They are advisory signals, not proof that work is inside or outside scope. Overview marks incomplete snapshots; absence of a warning must not be treated as proof that no overlap or drift exists.

Notifications identify normalized lifecycle conditions such as a question, approval request, failure, or completion. They help route attention but do not answer a question, approve an action, or alter an agent run.

Understand agent event privacy and retention

Structured event collection is enabled by default. Free-text event summaries are disabled by default. p-track retains at most the most recent 128 accepted events for a run and removes events older than 14 days under the default policy.

The provider input is a closed structured contract. It does not accept raw provider JSON, prompts, messages, tool payloads, command arguments or output, transcripts, environment data, credentials, or hidden reasoning. Accepted fields are normalized and bounded; project paths must remain project-relative. Credential-like or reasoning-like content is rejected, and rejection messages do not echo the rejected input.

Capability brokering lives in pam

p-track does not broker HTTP, Git, or SSH access for agents; that belongs to the companion project pam. ptrack capability prints a pointer here and exits with an error.

Boundaries at a glance