Skip to content

docs(j5): the agent tools after linked environments - #954

Merged
Jacksondr5 merged 1 commit into
j5/mainfrom
j5code/agent-tool-boundary-docs
Nov 7, 2026
Merged

Jacksondr5 merged 1 commit into
j5/mainfrom
j5code/agent-tool-boundary-docs

Conversation

@Jacksondr5

Copy link
Copy Markdown
Owner

Problem

J5's agent tools and upstream's overlap: both can spawn, stop, wait on and message agents. Upstream v0.1.7 adds linked environments, so the overlap now crosses machines too. Decision 3 of the v0.1.7 advance (J5-to-J5 delegate_task) couldn't be settled without first deciding where the line between J5's tools and upstream's sits. Jackson settled it on 2026-11-06 and 2026-11-07. This PR writes those rulings into the definitions, so the build follows them. Closes #952.

What changed

Definitions only. They describe the end state; the code follows in later PRs.

  • The line.
    • J5 owns who agents are and how they talk: participants, the ledger, Exchanges and Peer Agents. It also owns messaging across machines (peering), Crews, and personas as a parameter on whatever starts an agent.
    • Upstream owns delegates, stopping, waiting, thread housekeeping, scheduling, and acting on another machine (links).
  • Delegates (register D1, glossary, docs(j5): call a delegate_task child a delegate, and keep Subagent for a provider's own #952).
  • Peer Agents (agent-tools.md, cross-device.md).
    • Peer Agents stay on j5_spawn_agent.
    • It gains environment_id, to start a Peer Agent on another J5 machine over a link. The spawner is passed along and recorded as outside agents are; the caller gets a participant id it can message at once.
    • A cross-machine spawn needs a Full access link plus peering.
    • The workspace stays required.
  • Stopping (D2, agent-tools.md). j5_stop_agent retires for upstream's t3_thread_interrupt, whose stop: true is the full Stop. J5 keeps one rule on it: a Captain may stop its own seats whatever their access.
  • Admitted tools (D2, substrate).
    • t3_thread_wait and t3_thread_interrupt are admitted.
    • t3_thread_launch is admitted only for link sessions, so upstream's remote delegation works into a J5 machine. Threads it launches with delegatedFrom stay out of the ledger.
    • The link tools are kept.
    • t3_thread_send stays hidden.
    • j5_list_participants rows carry thread_id.
  • Remote delegates (D42). A persona can be delegated to another J5 machine and is resolved from that machine's library. A plain delegate there is held to that machine's model lists.
  • Naming rule (D2). J5 adds personas and refusals to upstream's tools under upstream's names. A tool gets a J5 name only when J5 changes what it means.
  • Cross-device. "No agent tool chooses or manages a server" narrows to J5's messaging verbs, which is decision 1's AC16 rewrite, done here so the sentence changes once. A new section covers starting work on another machine. Its Later list links Reverse route: let the VM reach a laptop that can't be reached, over a line the laptop opens #951 (reaching an unreachable machine) and Crews cross machines: a Captain seats members on another J5 machine #953 (Crews across machines).
  • Record. docs/j5/worklog/2026-11-07-agent-tool-boundary-session.md has the prior rulings, what was found, the rulings, and how each point from an adversarial review (GPT-6.1 Sol) was settled.

Not changed on purpose:

  • The three "Description (contract)" strings in agent-tools.md. tools.test.ts pins them byte-for-byte to the shipped tool descriptions, so they change in the build PR together with the code.
  • User docs that describe shipped behaviour (beyond the delegate term) and the agent-migration runbook. They follow the code.
  • FORK.md. This PR edits no code.

Overlap with open work:

Checklist

  • One concern: the description has no "also". Not ticked: docs(j5): call a delegate_task child a delegate, and keep Subagent for a provider's own #952's term change rides along at Jackson's request, because it touches the same files.
  • Tests cover the changed behavior. Not applicable: docs only. The two tests that read agent-tools.md (tools.test.ts, EnvelopeFormatter.test.ts) pass.
  • UI changes: before/after screenshots above. Not applicable: no UI change.
  • Live testing: not applicable, docs only.
  • Upstream-owned files: not applicable, no code. The build will add FORK.md cases (J5's interrupt and launch, the persona passed through RemoteDelegation.ts).
  • Upstream product: the changes to what upstream's product does are recorded in register entries D1, D2 and D42, with the decisions in the session record.
  • Surfaces: not applicable to a docs PR; the build PRs carry it.
  • Docs: definitions under docs/j5/product/ rewritten, plus docs/j5/user/personas.md for the term.

Drafted with Claude Opus 5.5 in J5 Code (Claude Code harness).

🤖 Generated with Claude Code

Records the agent-tool rulings made for the v0.1.7 advance: J5 owns
messaging, Peer Agents, peering, Crews and personas, and follows upstream
for delegates, stopping and waiting. Peer Agents stay on j5_spawn_agent and
can start on another J5 machine; j5_stop_agent retires for
t3_thread_interrupt with a Captain rule; t3_thread_wait is admitted;
t3_thread_launch is admitted for link sessions only. A delegate_task child
is called a delegate (#952).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vercel

vercel Bot commented Nov 7, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
j5-code Ready Ready Preview Nov 7, 2026 6:34pm UTC

Request Review

This branch was successfully deployed

1 active deployment
Preview — ee1bfcbb Deployed Nov 7, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size:L 100-499 effective changed lines (test files excluded in mixed PRs). vouch:trusted PR author is trusted by repo permissions or the VOUCHED list.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs(j5): call a delegate_task child a delegate, and keep Subagent for a provider's own

1 participant