# Tools

The plugin registers `seed_*` tools for lab coordination:

- Task state: `seed_task_create`, `seed_task_get`, `seed_task_list`, `seed_task_update`
- Delegation: `seed_delegate`, `seed_delegate_background`, `seed_delegate_followup`
- Team runtime: `seed_team_send`, `seed_team_broadcast`, `seed_team_inbox`, `seed_team_ack`, `seed_team_status`, `seed_team_roster`, `seed_team_conversation`, `seed_team_meeting_create`, `seed_team_meeting_post`, `seed_team_meeting_status`, `seed_team_meeting_close`, `seed_team_list`, `seed_team_cleanup`, `seed_team_member_update`, `seed_team_member_followup`, `seed_team_member_add`, `seed_team_member_request`, `seed_team_task_create`, `seed_team_task_list`, `seed_team_task_claim`, `seed_team_task_release`, `seed_team_task_update`
- Sub-plans: `seed_subplan_create`, `seed_subplan_list`, `seed_subplan_transition`, `seed_subplan_verify`
- Workspace coordination: `seed_workspace_intent`, `seed_workspace_lease_acquire`, `seed_workspace_lease_refresh`, `seed_workspace_lease_release`, `seed_workspace_conflict_resolve`, `seed_workspace_diff_record`, `seed_workspace_worktree_merge_record`, `seed_workspace_status`
- Trace/evidence/telemetry/artifacts/policy: `seed_trace_event`, `seed_trace_read`, `seed_continuation_read`, `seed_context_bundle_list`, `seed_context_bundle_read`, `seed_context_metrics`, `seed_model_route`, `seed_run_telemetry`, `seed_artifact_list`, `seed_artifact_read`, `seed_policy_audit`, `seed_evidence_add`
- Orchestrator loop: `seed_orchestrator_next`, `seed_orchestrator_tick`, `seed_orchestrator_record_decision`
- Coordinator discipline: `seed_coordinator_direct_work`
- Progress/report: `seed_progress_write`, `seed_report_check`, `seed_report_write`, `seed_report_export`
- Session context: `seed_session_list`, `seed_session_read`, `seed_session_search`, `seed_session_info`
- Checks/scripts: `seed_tool_policy_check`, `seed_run_check`, `seed_run_script`, `seed_command_status`
- Background: `seed_background_start`, `seed_background_checkpoint`, `seed_background_notifications`, `seed_background_output`, `seed_background_followup`, `seed_background_cancel`
- Skills/media/documents/handoff: `seed_skill`, `seed_skill_recommend`, `seed_skill_mcp`, `seed_skill_validate`, `seed_browser_snapshot`, `seed_document_extract`, `seed_look_at`, `seed_handoff_to_professor`

Native OpenCode tools remain the file and shell execution surface; SEED does
not define `seed_edit`, `seed_write`, or a generic `seed_run` replacement.
The SEED tool list is manifest-backed: every `seed_*` tool has an explicit
surface category, and unrecognized future `seed_*` names fail closed for member
policy until the manifest is updated.
Powerful commands are screened for destructive patterns and should route through professor handoff when unsafe.
`seed_tool_policy_check` exposes the same allow/ask/deny command-policy decision
without executing the command. `seed_run_check`, `seed_run_script`, and
`seed_background_start` use that centralized policy before spawning tracked
verification or background processes. Those three command-execution tools are
reserved for the root Lab-Representative; ordinary members use native OpenCode
shell tools only when their contract, read/write paths, and leases allow it.
If OpenCode aborts a running command/background process, SEED kills the child
process, records the cancellation in trace/background state, and refreshes
continuation context.

Main SEED tasks can declare `depends_on`. `seed_task_update` refuses to move a
dependent task into `in_progress`, `review`, or `completed` until every listed
dependency task is completed. This keeps the professor-facing task board as
executable state instead of a loose checklist.

Coordinator-mode `/seed` runs treat Lab-Representative as the planner,
dispatcher, verifier, and reporter by default. The root Lab-Representative
session is blocked from direct native edit/write/bash writes unless it first
records a one-shot exception with `seed_coordinator_direct_work`. Dynamic member
sessions still use native tools through their member contract, write paths, and
workspace leases.

## Team Runtime

Team runtime tools persist state under `.seed-agent/runs/<run_id>/team/`.
Messages are delivered to per-member inboxes, acknowledgements are recorded,
member status is stored in `runtime.json`, and shared team tasks can be
created, claimed, released, updated, listed, and resumed. Claiming, blocking,
completing, cancelling, or releasing a team task refreshes the owner's durable
member status so `/seed-status`, continuation snapshots, and team tools see the
same shared state. Team tasks carry a monotonically increasing `revision`.
`seed_team_task_update` can pass `expected_revision`; if the current task has
moved on, SEED records a durable `stale_revision` conflict, blocks the task, and
keeps the stale patch from overwriting current owner, status, or evidence.
`seed_team_cleanup` completes the team runtime only after open team tasks and
unread team messages are resolved, then writes `team/cleanup.json` with task and
inbox counts. Use team tasks for coordination between lab members; use the main
SEED task board for the professor-facing acceptance path.

Team meeting tools create durable discussion threads under
`.seed-agent/runs/<run_id>/team/meetings/`. Use
`seed_team_meeting_create` when multiple members need to align on an agenda,
`seed_team_meeting_post` for messages, decisions, and action items, and
`seed_team_meeting_close` once the decision is summarized. Open meeting context
is injected into participant turns and continuation snapshots, while
`seed_team_broadcast` fans out a stateful announcement through member inboxes.

The orchestrator loop tools give Lab-Representative a durable coordinator
scratchpad under `.seed-agent/runs/<run_id>/orchestrator-loop.jsonl`.
`seed_orchestrator_next` computes the next action from mailbox, sub-plan,
meeting, and feedback-gate state; `seed_orchestrator_tick` records a loop tick;
and `seed_orchestrator_record_decision` records why the representative chose a
dispatch, wait, or verification step.
Tick and decision calls accept optional idempotency keys; repeated keys return a
deduplicated result instead of appending another coordinator event.

Ordinary members should not recursively spawn more agents by default. When a
member needs a new role, task, meeting, or delegation, it should call
`seed_team_member_request`; SEED records the request under
`team/member-requests.json` and sends a handoff message to Lab-Representative.
Direct delegation tools remain blocked for member sessions unless the durable
member `spawn_policy` explicitly allows it without Lab-Representative approval.

`seed_team_create` requires an explicit `inline_spec`. The core does not create
document-review, web-app, automation, or other domain rosters from
`workflow_template`. Lab-Representative can still include
`workflow_template.name` and required coverage as metadata inside the spec, but
the actual members, tool policy, write paths, evidence obligations, and stop
conditions must be present in the inline spec itself.

`seed_team_member_followup` targets an existing team member by role id and
continues that member's child session when it is idle, or leaves the message in
the durable mailbox when the member is busy. `seed_team_member_add` expands an
active dynamic team with a new inline member spec, validates the expanded
contract against max-member, policy, and write-path overlap rules, creates the
new inbox, launches a child session, and announces the join to the team.
Initial member launches and live follow-ups both send the member's resolved
OpenCode `tools` map with the prompt body. Each dynamic member is also recorded
as an agent-thread under `threads/threads.json`, with its tool manifest written
to `threads/<thread_id>/tool-manifest.json`. The same policy data is recorded
in `team/conversation.jsonl` as `session_tools`, alongside `allowed_tools`,
`denied_tools`, `allowed_skills`, `prompt_ref`, child session id, background
id, and agent-call metadata, so a later audit can verify what the member was
actually allowed to use.
Each member's durable contract is also reinjected into that member's future
model turns and compaction context so long-running sessions keep their role,
tool policy, MCP/skill policy, read/write scope, evidence obligations, and stop
condition even after context growth.
The same durable contract is enforced before tool execution: member sessions
cannot call denied or unlisted tools, and write/append workspace intents or
leases outside their `write_paths` are blocked and recorded in the trace.
Member-to-member communication uses durable message envelopes, not ad hoc
prompt copying: `seed_team_send` writes the recipient inbox, appends
`messages/envelopes.json`, records delivery attempts in `messages/delivery.jsonl`,
and appends `team/conversation.jsonl`; `seed_team_ack` marks consumed messages
and appends the acknowledgement. The conversation log is the quickest debug
path for reconstructing what the Lab-Representative asked each virtual member
to do and which messages were actually consumed. Use `seed_agent_thread_status`,
`seed_agent_thread_trace`, `seed_message_queue`, and `seed_team_conversation`
to read these logs from inside OpenCode. Entries include explicit `from` and
`to` fields plus launch ids, agent call ids, child session ids, background ids,
helper ids, prompt refs, delivery status, allowed/denied tools, MCP/skill
policy, read/write paths, and other member-contract metadata when available.
This is the primary ordered trace for Lab-Representative-to-member,
member-to-Lab-Representative, and member-to-member communication.
Message envelopes can also carry `context_refs` and `context_attachments`.
Use `seed_context_bundle_list` to see stored stable/warm/hot/heavy/memory
bundles, `seed_context_bundle_read` to inspect one bundle body, and
`seed_context_metrics` to see recent injection plans and budget counters.
These tools are read-only and safe for member sessions.

Sub-plans with `write_paths` must bind active write leases before entering
`executing`. Pass `subplan_id` to `seed_workspace_lease_acquire` to attach the
granted lease to the sub-plan, then use native OpenCode edit/write/bash tools
inside the member's allowed workspace. After the native write is verified,
record `seed_workspace_diff_record` with the changed paths, lease ids, and
sub-plan id; main-workspace diff records require active write-lease coverage for
their changed paths. Worktree-isolated sub-plans can execute without a main-workspace
lease, but their changes do not count as completed main-workspace work until
Lab-Representative or the sub-plan's `merge_owner_member` records
`seed_workspace_worktree_merge_record`. That merge record requires an active
main-workspace write lease covering the target paths, a worktree diff ref, and a
main-workspace diff ref. Out-of-scope worktree paths can be recorded as rejected
evidence without being merged. Final completion is blocked when required
accepted write sub-plans have no recorded diff ref, when a diff ref cannot be
found, when a recorded diff touches paths outside the sub-plan `write_paths`,
when a required worktree sub-plan lacks an applied merge record with both diff
refs, or when workspace conflicts remain open. Lease conflicts can open a
durable team meeting agenda so the decision and action items are available as
conflict-resolution evidence.

## Continuation Context

SEED writes compact continuation snapshots under
`.seed-agent/runs/<run_id>/continuation/`. The snapshot includes the active run,
open tasks, blockers, evidence refs, team unread counts, shared team tasks,
background work, pending background notifications, pending professor decisions, a prioritized `next_actions`
queue, and recent trace events. The plugin can inject this context into future
user turns and OpenCode compaction prompts when
`continuation` config is enabled. During OpenCode compaction, SEED adds only
runtime bridge context: continuation summary, team roster, open meetings,
member contract/memory, unread member mailbox, and background status. It does
not run a second compaction scheduler or summarizer. Background terminal states and professor
handoff requests refresh the snapshot immediately so the next agent turn sees
the latest decision point and the next concrete actions to take. Terminal
background work also creates durable parent-session notifications in
`background_notifications.json`; chat hooks can deliver those notices to the
parent session, and continuation snapshots keep them visible until delivery.

`seed_continuation_read` exposes the same continuation snapshot and prioritized
`next_actions` queue as a tool. By default it refreshes
`continuation/context.json` and `continuation/context.md` before returning the
machine-readable queue, so a worker can resume from durable state instead of
depending on hidden chat history.
Chat and compaction hooks store repeated continuation/team/member context in
the context ledger, then inject a bounded attachment plan. This preserves the
same durable resume information while reducing repeated raw prompt text.

Delegation tools create real OpenCode child sessions through the host SDK and run
the requested target agent. `seed_delegate_followup` continues an existing
child session by `session_id` or `background_id`; it does not create a new
session for a follow-up. Delegation resolves the target agent's model profile,
passes explicit `provider/model` routing when configured, retries configured
fallbacks on retryable model/provider failures, and records requested, resolved,
and attempted models in `agent_calls.jsonl`. Attempt records include immutable
`attempt_id`, `current`, and `stale` fields so retry history can be debugged
without confusing an old failed attempt with the current child-session state.
Delegation calls can also carry an optional `idempotency_key` for duplicate
dispatch detection. Session tools call OpenCode session APIs directly.
Use `seed_model_route` before unusual or high-risk delegation to inspect the
configured model profile, provider/model attempts, fallback count, and warnings
without launching a child session.
`seed_delegate` and `seed_delegate_background` can also receive
`skills: ["skill-name"]`. SEED loads those project/user `SKILL.md` files,
checks required MCP diagnostics, blocks the delegation when a required MCP is
unavailable, and otherwise injects a `<seed-skill-context>` block into the child
session prompt. They can also receive `auto_skills: true`; SEED then recommends
ready skills from the task prompt and target agent before launching the child
session. The injected skill bodies are stored as run artifacts and traced with
`delegation_skill_context_loaded`.
Background cancel sends `SIGTERM` to spawned processes or aborts OpenCode child
sessions; it is not a trace-only marker.

Use `seed_background_checkpoint` for long-running work. A checkpoint observes
the current child session once, records status in the run trace, appends a short
progress note, and returns the next action. It does not wait indefinitely,
cancel the work, or treat long duration as failure.

Use `seed_background_followup` when the professor intervenes while an OpenCode
background child session is still running. It sends the intervention into the
existing child session with `promptAsync`, records `background_followup_sent`,
and updates `background_tasks.json` so `/seed-status` shows the latest
intervention. Process background tasks cannot receive prompt follow-ups; for
those tasks the tool records the message and returns `recorded_only`.

`seed_background_output` can return either the compact output tail or a filtered
full child-session transcript:

```jsonc
{
  "background_id": "bg_...",
  "full_session": true,
  "since_message_id": "msg_...",
  "include_tool_results": true,
  "message_limit": 50
}
```

`seed_background_notifications` lists durable pending, delivered, or dismissed
background completion notices. Use it when resuming a long run to see which
background child sessions still need parent review before reading full output.

`seed_run_telemetry` builds a structured quality summary for a run. It reads
the run state, tasks, events, agent calls, tool calls, evidence ledger, and
final report; writes `artifacts/run-telemetry.json`; and returns task/tool/agent
counts, model-attempt counts, evidence coverage, and quality-gate warnings.

`seed_artifact_list` reads the versioned artifact index at
`artifacts/index.json`. Artifacts written by SEED tools are indexed with schema
version, relative path, extension, size, and timestamps. If an older run has
artifact files but no index, reading the index initializes it from the existing
artifact directory.
`seed_artifact_read` reads one indexed artifact by `artifact_id` or relative
path, returns bounded text content, emits an `artifact_read` trace event, and
runs the policy audit on the artifact content so replayed evidence remains
inspectable and safety-checked.

`seed_policy_audit` checks final report, progress, evidence, or provided text
for secret-looking values, machine-specific local paths, and
prompt-injection-like text. It writes `artifacts/policy-audit.json`. When
`safety.redact_secrets` is enabled, `seed_report_write` with
`status: "completed"` blocks final reports that contain secret or local-path
policy findings before the run can be closed.

`seed_report_check` checks `final_report.md` or provided report content against
the evidence ledger and task evidence refs, then writes
`artifacts/report-gate.json`. When `run.review_before_final` is enabled,
`seed_report_write` with `status: "completed"` enforces the same gate before it
writes the final report or closes the run. Exceptional professor-approved cases
can pass `bypass_review_gate: true`, but the default path requires cited
`evidence.md#...` anchors.

`seed_skill` loads `SKILL.md` files from project skill directories such as
`.seed-agent/skills/<name>/SKILL.md`, `.opencode/skills/<name>/SKILL.md`, and
`.agents/skills/<name>/SKILL.md`. User skill directories are also available
when `skills.allow_user_skills` is enabled. Loaded skills return their source,
metadata, body, artifact `content_ref`, required/optional MCP declarations, and
MCP diagnostics. `seed_skill_recommend` ranks discoverable skills for a task
query, target agent, and optional category using `name`, `description`,
`keywords`, `triggers`, `tags`, `agents`, `categories`, and required MCP
readiness. It writes the recommendation set as a run artifact. `seed_skill_mcp`
returns the workspace MCP inventory or the
same requirement diagnostics for one skill. `seed_skill_validate` statically
checks project skills for metadata, duplicate names, empty bodies, and required
MCP availability, then writes a JSON validation report artifact. User skill
validation is opt-in with `include_user: true` so project checks stay
reproducible in fresh clones.

`seed_browser_snapshot` launches a bounded headless browser capture path for a
local file, or for an external http(s) URL only when the call explicitly sets
`allow_external: true`. It uses an isolated temporary browser profile, writes a
`type: "seed.browser_snapshot"` JSON artifact, stores a PNG screenshot artifact
when the browser provides one, and immediately routes the snapshot through
`seed_look_at` inspection so the result lands in the evidence ledger. A custom
browser command is allowed only when the executable name is a known
Chromium/Firefox browser or the call explicitly sets
`allow_custom_browser_command: true`. Captured HTML is reduced to visible text
with simple hidden-element stripping before it becomes browser snapshot text;
hidden text, ARIA/title prompt-injection cues, and unsafe URL references remain
recorded as security findings.

`seed_document_extract` is the local PDF text-ingestion path. It shells out to
`pdftotext`, honoring `SEED_PDFTOTEXT_BIN` first and `PDFTOTEXT_BIN` as a
compatibility alias, then PATH. It writes metadata, extractor, normalized text,
page JSONL, chunk JSONL, and extraction-report artifacts under
`artifacts/documents/<document_id>/`, indexes each artifact, records evidence,
and reports Linux-focused recovery guidance when `pdftotext` is unavailable.
That guidance is intentionally non-deterministic: Lab-Representative should
inspect the distro, package manager, PATH, sudo behavior, network/policy
constraints, and package candidates before proposing or running any install
command. Any side-effecting install must still go through SEED/OpenCode policy
gates. If installation is blocked, Lab-Representative should record the blocker
and the exact admin command to run. Set `SEED_PDFTOTEXT_BIN` to an explicit
`pdftotext` binary path when PATH does not expose it.

`seed_look_at` inspects supported local images, screenshots, PDFs, text
documents such as HTML, Markdown, plain text, and JSON, and browser snapshot JSON
files with `type: "seed.browser_snapshot"`. It records file provenance, MIME
type, size, SHA-256, extracted findings, an artifact JSON, and an evidence
entry. Text document and browser snapshot inspection also run the SEED policy
audit so prompt-injection-like instructions, secrets, or local-path leaks are
recorded as evidence findings rather than followed as operator instructions.
Browser snapshot content is always marked `browser_snapshot_untrusted`, and a
linked `screenshot_path` is checked as a local image with size, hash, MIME, and
dimension metadata. External URLs are not fetched by `seed_look_at`; they are
marked as untrusted unless a separate `seed_browser_snapshot` capture has already
materialized them into a local snapshot artifact. Text and browser snapshot
artifacts also include a `seed.trust_boundary` envelope summary for untrusted
content. The envelope escapes nested boundary markers, reports warning counts,
and redacts configured `security_canaries` when recording excerpts; matching
canary tokens fail the policy audit as `no_canary_token_leak`.
For PDFs, `seed_look_at` remains a quick provenance/metadata inspection. Use
`seed_document_extract` when a document/PDF task needs page and chunk artifacts
that a final report can cite.

Persistent browser sessions are intentionally not enabled yet. The planned
sidecar boundary, lifecycle state, security policy, and eval requirements are
tracked in `docs/browser-media-sidecar.md`.
