Experimental: multi-agent foundation (Phase 0) — AgentDefinition + tier slots + TOML registry

.jcode/agents/basher.toml

@@ -0,0 +1,80 @@
+# Basher agent.
+#
+# Spawned by the orchestrator to run a single terminal command and
+# summarize its output. The classic "shell out for a quick fact"
+# helper — git status, ls, cargo metadata, ripgrep one-liners.
+#
+# Why `prefer_tier = "routine"`:
+#   Running a command and paraphrasing its stdout is a cheap+fast task.
+#   A pay-per-token user with `JCODE_ROUTING_ROUTINE=<cheap-model>`
+#   keeps the cost of these frequent leaf calls low. Subscription
+#   users inherit the session model and get correct behavior without
+#   any tier mapping.
+#
+# Why `include_message_history = false`:
+#   Each command should be evaluated on its own — feeding parent edit
+#   chatter into a one-shot bash invocation just wastes tokens and
+#   risks the agent acting on stale context. Clean slate per command.
+#
+# Why `inherit_parent_system_prompt = false`:
+#   This is a tightly scoped leaf agent. It needs its own short prompt,
+#   not the parent's full project/system prompt. No prompt-cache
+#   prefix-sharing benefit either, because the bash tool's I/O is the
+#   real bulk of the request.
+#
+# SECURITY NOTE:
+#   This agent will execute whatever command the parent passes in. The
+#   bash tool's safety/permission layer applies, but the *caller* must
+#   still validate that the command is what it intends. Never feed
+#   unsanitized user input directly into the spawn payload — quote and
+#   escape arguments, or build the command server-side from a whitelist.
+
+id = "basher"
+display_name = "Basher"
+publisher = "jcode"
+version = "0.1.0"
+
+prefer_tier = "routine"
+reasoning = "minimal"
+
+# Basher runs terminal commands — auto-approve file ops so the parent
+# doesn't need to re-approve every bash call. Network/spawn still prompt.
+permission_mode = "accept-edits"
+max_turns = 10
+
+include_message_history = false
+inherit_parent_system_prompt = false
+output_mode = "last_message"
+
+# Single tool: jcode's terminal command runner.
+tool_names = ["bash"]
+
+# Leaf agent — does not spawn other agents.
+spawnable_agents = []
+
+spawner_prompt = """
+Spawn this agent to run a single terminal command and get a short
+summary of its output. Pass the exact command plus an optional
+`what_to_summarize` hint; if you need full raw output, leave the hint
+empty and the agent will return the output verbatim.
+"""
+
+system_prompt = """
+You are an expert at running terminal commands and summarizing their
+output.
+
+Inputs you receive:
+- the command to run (required).
+- an optional `what_to_summarize` hint describing which parts of the
+  output the caller cares about.
+
+If `what_to_summarize` is empty, return the raw command output verbatim
+without paraphrasing.
+"""
+
+instructions_prompt = """
+Run the command using the `bash` tool exactly as provided. Then describe
+the relevant information from the output, focused on what the caller
+asked for. Be concise. Do not suggest follow-up commands or next steps —
+the parent decides what happens next.
+"""

.jcode/agents/code-reviewer.toml

@@ -0,0 +1,80 @@
+# Code reviewer agent.
+#
+# Spawned by the orchestrator after non-trivial code changes to catch
+# bugs and style regressions before the user sees them. Adapted from
+# Codebuff's `code-reviewer`.
+#
+# Why `prefer_tier = "thinking"`:
+#   Review work benefits from reasoning. A pay-per-token user with
+#   `JCODE_ROUTING_THINKING=<premium-model>` gets the right model
+#   for the right job; subscription users inherit the session model.
+#
+# Why `inherit_parent_system_prompt = true`:
+#   This is the prompt-cache prefix-sharing trick. When parent and
+#   child share an identical system prompt prefix, the provider's
+#   prompt cache delivers a cache hit on the child invocation —
+#   typically ~90% input-token savings on Anthropic models.
+#
+#   IMPORTANT: must leave `system_prompt` empty (validated). The
+#   `instructions_prompt` is the only per-agent prompt this reviewer
+#   adds on top of the inherited system prompt.
+
+id = "code-reviewer"
+display_name = "Code Reviewer"
+publisher = "jcode"
+version = "0.1.0"
+
+prefer_tier = "thinking"
+reasoning = "medium"
+
+inherit_parent_system_prompt = true
+include_message_history = true
+output_mode = "last_message"
+
+# Reviewer is read-only — plan mode denies writes without prompting.
+permission_mode = "plan"
+max_turns = 15
+
+tool_names = [
+    "read",
+    "grep",
+]
+
+# Reviewers don't spawn other agents — they read, reason, and report.
+spawnable_agents = []
+
+spawner_prompt = """
+Spawn this agent after non-trivial code changes to review them. The
+reviewer reads the diff, considers project conventions, and reports
+strengths and weaknesses. Do not pass a custom prompt — the reviewer
+inherits the conversation context and forms its own assessment.
+"""
+
+# system_prompt MUST be empty when inherit_parent_system_prompt is true.
+# The shared parent prompt covers project context, conventions, and
+# tools; the reviewer's specialization is purely in instructions_prompt.
+
+instructions_prompt = """
+You are reviewing the code changes just made by another agent.
+
+Focus on:
+- Correctness: does the code do what the user asked?
+- Project conventions: imports, formatting, naming, error handling.
+- Test coverage: are new code paths exercised?
+- Edge cases: what could go wrong? What was missed?
+
+Format your output as:
+
+  Strengths
+  - bullet (concrete reference to file/line where possible)
+
+  Concerns
+  - bullet (concrete reference to file/line where possible)
+
+  Required fixes (if any)
+  - bullet
+
+Be terse. Be specific. Do not restate code that's already in the diff.
+If the change is solid and you have no concerns, write a single
+sentence saying so.
+"""

.jcode/agents/editor.toml

@@ -0,0 +1,91 @@
+# Code editor agent.
+#
+# Spawned by the orchestrator to perform precise, reasoned code edits.
+# Reads files first, prefers surgical `str_replace`-style edits over
+# whole-file rewrites, and matches the surrounding project's style.
+#
+# Why `prefer_tier = "thinking"`:
+#   Edits need reasoning — a wrong substitution silently breaks the
+#   build or, worse, changes behavior in a way tests don't catch. A
+#   pay-per-token user with `JCODE_ROUTING_THINKING=<premium-model>`
+#   gets the right tool for the job; subscription users inherit the
+#   session model.
+#
+# Why `inherit_parent_system_prompt = true`:
+#   This is the prompt-cache prefix-sharing trick — the biggest
+#   single-knob token-cost win in the harness. When parent and child
+#   share an identical system prompt prefix, the provider's prompt
+#   cache delivers a cache hit on the child's first turn, typically
+#   ~90% input-token savings on Anthropic models. The editor is one
+#   of the most-spawned sub-agents, so this matters.
+#
+#   IMPORTANT: `system_prompt` MUST be empty when
+#   `inherit_parent_system_prompt = true`. The runtime's
+#   `AgentDefinition::validate` enforces this and refuses to load the
+#   agent otherwise. Per-agent specialization lives in
+#   `instructions_prompt` only.
+#
+# Why `include_message_history = true`:
+#   The editor needs to see what the user asked for and any prior
+#   discussion that shaped the requested change. Without history it
+#   would re-derive context the parent already has.
+
+id = "editor"
+display_name = "Code Editor"
+publisher = "jcode"
+version = "0.1.0"
+
+prefer_tier = "thinking"
+reasoning = "medium"
+
+# Editor makes code edits — auto-approve file operations so the parent
+# agent doesn't need to re-approve every str_replace/write call.
+permission_mode = "accept-edits"
+
+inherit_parent_system_prompt = true
+include_message_history = true
+output_mode = "all_messages"
+
+# system_prompt MUST be empty when inherit_parent_system_prompt = true
+# (validated at load time). Specialization is purely in
+# instructions_prompt below.
+
+# Edit-focused tool surface: read first, then surgical edits, with
+# whole-file write available as a last resort.
+tool_names = [
+    "read",
+    "str_replace",
+    "write",
+    "edit",
+    "multiedit",
+    "apply_patch",
+    "hashline_edit",
+    "patch",
+]
+
+# Leaf agent — performs the edit itself; does not spawn helpers.
+spawnable_agents = []
+
+spawner_prompt = """
+Spawn this agent for precise code edits that need reasoning. The editor
+reads the relevant files, makes the requested change, matches existing
+project conventions, and reports what it changed. Use it when a single
+substitution or small multi-file edit is well-scoped.
+"""
+
+instructions_prompt = """
+You are an expert code editor.
+
+Make the requested edit:
+1. Read the target file(s) first to confirm current contents.
+2. Prefer `str_replace` over `write` — surgical substitutions are
+   safer and produce smaller diffs than whole-file rewrites.
+3. Match existing project conventions (imports, formatting, naming,
+   error handling). Look at sibling code if unsure.
+4. Do not introduce new dependencies. If the change appears to need
+   one, stop and report instead of adding it.
+
+After the edit, briefly state what was changed (file paths + a
+one-sentence summary). Do not restate code already visible in the
+edit's diff.
+"""

.jcode/agents/file-picker.toml

@@ -0,0 +1,75 @@
+# File picker agent.
+#
+# Spawned by the orchestrator to find files in the codebase that are
+# relevant to a task. Adapted from Codebuff's `file-picker` agent.
+#
+# Why `prefer_tier = "routine"`:
+#   File picking is a fuzzy-search task — a smaller/cheaper model
+#   handles it well. Pay-per-token users who set
+#   `JCODE_ROUTING_ROUTINE=<cheap-model>` save real money here.
+#   Subscription users (Claude Pro, ChatGPT Plus, ...) inherit the
+#   session model and get correctness without any tier mapping.
+#
+# Why `include_message_history = false`:
+#   File picker doesn't need to see prior edit chatter. A clean slate
+#   keeps the prompt short and avoids accidentally biasing path
+#   selection toward already-touched files.
+#
+# Why `inherit_parent_system_prompt = false`:
+#   Like basher, this is a tightly scoped leaf agent. It needs its own
+#   short prompt focused on file discovery, not the parent's full
+#   project/system prompt.
+
+id = "file-picker"
+display_name = "Fletcher the File Fetcher"
+publisher = "jcode"
+version = "0.1.0"
+
+prefer_tier = "routine"
+reasoning = "minimal"
+
+include_message_history = false
+inherit_parent_system_prompt = false
+output_mode = "last_message"
+
+# File picker is read-only — plan mode denies writes without prompting.
+permission_mode = "plan"
+max_turns = 5
+
+# Tools required: read project file tree + glob fallback. Whitelist is
+# checked at runtime against the tool registry; unknown tools fail loudly
+# rather than silently degrading.
+tool_names = [
+    "ls",
+    "glob",
+    "read",
+]
+
+# This agent is a leaf — it does not spawn other agents.
+spawnable_agents = []
+
+spawner_prompt = """
+Spawn this agent to find relevant files in the codebase. Provide a brief
+description of what you're looking for. The agent will return up to ~12
+file paths with one-line summaries. It does fuzzy semantic search; for
+exact-string searches, spawn a code searcher instead.
+"""
+
+system_prompt = """
+You are an expert at finding relevant files in a codebase. You have the
+project file tree and the user's request. Return the most relevant
+files, one per line, prefixed with the path. After the list, write a
+single short paragraph explaining how the files relate to the request.
+
+Do not read file contents — that is the parent agent's job.
+Do not propose changes — that is the editor's job.
+Stay focused on path discovery.
+"""
+
+instructions_prompt = """
+Provide an extremely concise report:
+1. List of relevant file paths (one per line).
+2. One paragraph (<= 4 sentences) explaining the relevance.
+
+Do not exceed 12 paths unless the parent explicitly asks for more.
+"""