@synapse-research/synapse 0.2.10 → 0.2.12

package/dist/public/synapse-plugin/bin/on-post-create-experiment.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# on-post-create-experiment.sh — PostToolUse hook for synapse_create_experiment
+# Triggered immediately after the agent creates an experiment.
+# Reminds the main agent that the next step is a sub-agent self-review
+# before the experiment is pushed to pending_review.
+#
+# Output: JSON with additionalContext (LLM-visible) + systemMessage (user toast)
+
+set -euo pipefail
+
+[ -z "${SYNAPSE_URL:-}" ] && exit 0
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+API="${SCRIPT_DIR}/synapse-api.sh"
+
+EVENT=""
+if [ ! -t 0 ]; then
+  EVENT=$(cat)
+fi
+
+if [ -z "$EVENT" ]; then
+  exit 0
+fi
+
+TOOL_NAME=$(echo "$EVENT" | jq -r '.tool_name // .toolName // empty' 2>/dev/null) || true
+case "$TOOL_NAME" in
+  *synapse_create_experiment) ;;
+  *) exit 0 ;;
+esac
+
+# Try to extract the new experiment UUID from the tool response.
+EXPERIMENT_UUID=$(echo "$EVENT" \
+  | jq -r '.tool_response.experiment.uuid // .tool_response.uuid // .response.experiment.uuid // empty' 2>/dev/null) || true
+
+if [ -z "$EXPERIMENT_UUID" ]; then
+  EXPERIMENT_UUID=$(echo "$EVENT" \
+    | jq -r '.tool_response.content[0].text // empty' 2>/dev/null \
+    | jq -r '.experiment.uuid // .uuid // empty' 2>/dev/null) || true
+fi
+
+if [ -n "$EXPERIMENT_UUID" ]; then
+  CONTEXT="[Synapse Plugin — Required next step after creating an experiment]
+You just created experiment ${EXPERIMENT_UUID}. It is in 'draft'.
+DO NOT push it to pending_review yet. First, spawn a sub-agent via the Task tool to self-review this draft. The sub-agent should call synapse_get_experiment, then evaluate:
+  - Is the objective specific and measurable?
+  - Is the methodology sound and reproducible?
+  - Are the success criteria aligned with the project's evaluationMethods?
+  - Is the compute budget realistic given current availability?
+The sub-agent returns its verdict to you in-session — it does NOT write to Synapse.
+Apply revisions with synapse_update_experiment_plan if needed.
+Then call synapse_update_experiment_status({ experimentUuid: \"${EXPERIMENT_UUID}\", status: \"pending_review\" }) and present the self-review summary plus plan summary to the user.
+Wait for the user's verbal approve / reject. On approve, call synapse_review_experiment with reviewNote quoting the user's words. On reject, summarize the user's revision request (including a quoted phrase) into reviewNote and call synapse_review_experiment with decision \"rejected\" — do NOT also call synapse_add_comment, the review tool writes the comment for you.
+If the autonomy skill has marked this session as full_auto, skip the user gate and call synapse_review_experiment directly with reviewNote: 'Full-auto session authorized by <ownerName> at <ISO time>. Self-review pass: <key points>.'"
+  USER_MSG="Synapse: experiment ${EXPERIMENT_UUID:0:8} drafted — run self-review next"
+else
+  CONTEXT="[Synapse Plugin — Required next step after creating an experiment]
+You just created an experiment in 'draft'. Spawn a Task sub-agent to self-review the plan, revise via synapse_update_experiment_plan if needed, then push it to pending_review with synapse_update_experiment_status. After that, present the self-review summary to the user and wait for verbal approve / reject. Approvals call synapse_review_experiment with the user's quoted words in reviewNote; rejections summarize the user's revision request into reviewNote (the review tool writes the comment automatically — do not double-write)."
+  USER_MSG="Synapse: experiment drafted — run self-review next"
+fi
+
+"$API" hook-output "$USER_MSG" "$CONTEXT" "PostToolUse"

package/dist/public/synapse-plugin/bin/on-post-submit-results.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# on-post-submit-results.sh — PostToolUse hook for synapse_submit_experiment_results
+# Triggered immediately after the agent submits experiment results.
+# Injects a hard reminder that the agent MUST now call synapse_save_experiment_report
+# to write the markdown experiment report. Runs while the agent is still alive,
+# so it can act on the reminder in its very next turn.
+#
+# Output: JSON with additionalContext (LLM-visible) + systemMessage (user toast)
+
+set -euo pipefail
+
+[ -z "${SYNAPSE_URL:-}" ] && exit 0
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+API="${SCRIPT_DIR}/synapse-api.sh"
+
+# Read event JSON from stdin
+EVENT=""
+if [ ! -t 0 ]; then
+  EVENT=$(cat)
+fi
+
+if [ -z "$EVENT" ]; then
+  exit 0
+fi
+
+# Only act on the submit-results tool. Tool names from CC arrive in either
+# the bare form ("synapse_submit_experiment_results") or the MCP-prefixed form
+# ("mcp__synapse__synapse_submit_experiment_results") depending on transport.
+TOOL_NAME=$(echo "$EVENT" | jq -r '.tool_name // .toolName // empty' 2>/dev/null) || true
+case "$TOOL_NAME" in
+  *synapse_submit_experiment_results) ;;
+  *) exit 0 ;;
+esac
+
+# Pull the experiment UUID out of the tool input so the reminder can be specific.
+EXPERIMENT_UUID=$(echo "$EVENT" \
+  | jq -r '.tool_input.experimentUuid // .input.experimentUuid // empty' 2>/dev/null) || true
+
+# Pull the outcome too — used only for phrasing.
+OUTCOME=$(echo "$EVENT" \
+  | jq -r '.tool_input.outcome // .input.outcome // empty' 2>/dev/null) || true
+
+if [ -n "$EXPERIMENT_UUID" ]; then
+  CONTEXT="[Synapse Plugin — Required next step after submitting results]
+You just called synapse_submit_experiment_results for experiment ${EXPERIMENT_UUID}${OUTCOME:+ (outcome=${OUTCOME})}.
+You MUST now immediately call synapse_save_experiment_report({ experimentUuid: \"${EXPERIMENT_UUID}\", title, content }) with a full markdown writeup (objective, methodology, results, analysis, charts where useful).
+This is required for success, failure, and inconclusive outcomes alike. Do not finish the task, hand off, or move on until the report has been saved. Do not post the writeup as a comment — use synapse_save_experiment_report."
+  USER_MSG="Synapse: results submitted for ${EXPERIMENT_UUID:0:8} — now save the experiment report"
+else
+  CONTEXT="[Synapse Plugin — Required next step after submitting results]
+You just called synapse_submit_experiment_results. You MUST now immediately call synapse_save_experiment_report({ experimentUuid, title, content }) with a full markdown writeup (objective, methodology, results, analysis). This is required for every outcome — success, failure, and inconclusive. Do not finish the task or move on until the report has been saved."
+  USER_MSG="Synapse: results submitted — now save the experiment report"
+fi
+
+"$API" hook-output "$USER_MSG" "$CONTEXT" "PostToolUse"

package/dist/public/synapse-plugin/bin/on-session-start.sh

@@ -169,7 +169,8 @@ Tool availability depends on the agent's Synapse roles. Public read/comment/noti
   - Claim / status-update tools are available only when the agent has the matching research-oriented role
 
 **Experiment Planning / Revision:**
-  - \`synapse_create_experiment({ researchProjectUuid, title, description, researchQuestionUuid?, priority?, status? })\` — create a brand-new experiment outside autonomous loop (defaults to \`pending_review\`)
+  - \`synapse_create_experiment({ researchProjectUuid, title, description, researchQuestionUuid?, priority?, status? })\` — create a brand-new experiment outside autonomous loop (defaults to \`draft\`; spawn a self-review sub-agent and revise before pushing to \`pending_review\`)
+  - \`synapse_review_experiment({ experimentUuid, decision, reviewNote?, assignedAgentUuid? })\` — PI/admin agents can approve into \`pending_start\` or reject back to \`draft\` from the terminal flow
   - \`synapse_get_experiment({ experimentUuid })\` — inspect the current experiment
   - \`synapse_get_comments({ targetType: \"experiment\", targetUuid })\` — read review feedback or @mention threads
   - \`synapse_update_experiment_status({ experimentUuid, status: \"draft\", liveStatus: \"writing\", liveMessage })\` — mark that you are drafting or revising the plan

package/dist/public/synapse-plugin/hooks/hooks.json

@@ -50,6 +50,26 @@
         ]
       }
     ],
+    "PostToolUse": [
+      {
+        "matcher": "mcp__synapse__synapse_submit_experiment_results|synapse_submit_experiment_results",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/bin/on-post-submit-results.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__synapse__synapse_create_experiment|synapse_create_experiment",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/bin/on-post-create-experiment.sh"
+          }
+        ]
+      }
+    ],
     "SubagentStart": [
       {
         "hooks": [

package/dist/public/synapse-plugin/skills/autonomy/SKILL.md

@@ -25,6 +25,17 @@ This is the **CC-client autonomous loop**. It does not depend on the server-side
 
 If the user explicitly asks for "human review before each experiment", switch to **review mode**: proposals land as `pending_review` and the loop pauses until they are approved externally.
 
+## Full-Auto Lives In This Session Only
+
+Full-auto mode for the CC-client autonomous loop is opted in **verbally** ("turn on autonomous loop", "full auto", "run until done") and lives only in the main agent's current session context. It does **not** flip the server-side `autonomousLoopEnabled` / `autonomousLoopMode` fields, and it does not write any state to Synapse.
+
+Full-auto is a one-way track. The only exits are:
+
+- The user explicitly says stop (or interrupts the session).
+- A hard external error makes progress impossible (compute exhausted, MCP failure, network partition that cannot be recovered).
+
+Self-review **never** pauses full-auto. Sub-agent timeouts in self-review do not pause full-auto. Advisory issues raised by self-review do not pause full-auto. The main agent applies a single revision pass when feasible and continues. Whatever the main agent decides, it must be reflected in the `reviewNote` of the resulting `synapse_review_experiment` call (see template below).
+
 ## Prompt Boundary
 
 Stay inside this skill when the work is about:
@@ -72,6 +83,12 @@ Each iteration of the loop follows the same shape. The main agent runs this unti
 
 5. **Check stop conditions**, then either return control to the user (normal case) or immediately re-run step 1 if the user asked for tight, unattended iteration within a single turn.
 
+## Self-Review Before `synapse_propose_experiment`
+
+Before calling `synapse_propose_experiment`, spawn a `Task` sub-agent to self-review the proposal text (motivation, hypothesis, method, success criteria, compute fit) against the project context and evaluation methods. Self-review is in-session only — it does **not** write to Synapse. Refine the proposal text based on the verdict, then call `synapse_propose_experiment`.
+
+The same applies after `synapse_create_experiment` lands a draft inside the loop: self-review the draft via a sub-agent, revise, then push to `pending_review` and (in full-auto) auto-approve.
+
 ## Monitor-Not-Executor
 
 The main agent does **not** SSH into GPU nodes, does **not** run training loops, and does **not** call `synapse_start_experiment` itself (unless the user explicitly tells it to run an experiment inline with no sub-agent). Its job is:
@@ -109,6 +126,26 @@ Exit the loop and report back to the user when any of these hold:
 
 On exit, summarize what was run, what was learned, the current state of the synthesis document, and any recommended follow-ups for a human.
 
+## Auto-Approve `reviewNote` Template (CC Full-Auto Only)
+
+When the main agent auto-approves a draft after a successful self-review:
+
+```
+synapse_review_experiment({
+  experimentUuid,
+  decision: "approved",
+  reviewNote: "Full-auto session authorized by <ownerName> at <ISO time>. Self-review pass: <key points>.",
+})
+```
+
+When self-review failed or timed out, use:
+
+```
+reviewNote: "Full-auto session authorized by <ownerName> at <ISO time>. Self-review skipped: <reason>."
+```
+
+Either way, full-auto continues — the `reviewNote` is the audit truth.
+
 ## Mutual Exclusion With The Server-Side Loop
 
 If `synapse_get_research_project` shows the project already has `autonomousLoopEnabled = true` and a loop agent assigned on the realtime side, do not also run the CC-client loop against it. Warn the user and either defer, or ask them to disable the server-side loop first — running both will double-dispatch proposals and reservations.

package/dist/public/synapse-plugin/skills/experiments/SKILL.md

@@ -33,10 +33,56 @@ Hand off to:
 If `synapse_get_assigned_experiments` returns empty, do not idle. Ask the user which path:
 
 1. **Execute an approved experiment** — list `pending_start` experiments in the project with `synapse_get_project_full_context` and ask which to start.
-2. **Flesh out a quick idea** — call `synapse_get_project_full_context`, then draft a plan with `synapse_create_experiment` (defaults to `pending_review`, or pass `status: "draft"` to keep refining).
+2. **Flesh out a quick idea** — call `synapse_get_project_full_context`, then draft a plan with `synapse_create_experiment` (defaults to `draft`; run a self-review sub-agent before pushing to `pending_review` per the "Create → Self-Review → Pending Review → Verbal Approve" section below).
 3. **Create the foundational experiment** — if the project has no completed experiments, offer the foundational template below.
 4. **Enter the autonomous loop** — hand off to **[autonomy](../autonomy/SKILL.md)** to propose and auto-dispatch the next experiment.
 
+## Create → Self-Review → Pending Review → Verbal Approve
+
+Every agent-created experiment goes through this sequence before reaching `pending_review`.
+
+1. `synapse_create_experiment(...)` — defaults to `draft`. The PostToolUse hook will remind you to run self-review next.
+2. Spawn a self-review sub-agent with the `Task` tool. Use a prompt similar to:
+   ```
+   Self-review experiment <experimentUuid> for project <projectUuid>.
+   Call synapse_get_experiment to read the plan. Then evaluate against the project's evaluationMethods:
+   - Is the objective specific and measurable?
+   - Is the methodology sound and reproducible?
+   - Do the success criteria align with the project's evaluation methods?
+   - Is the compute budget realistic given current availability (synapse_list_compute_nodes)?
+   Return a short verdict: "pass" or a bulleted list of concrete revisions.
+   Do NOT write back to Synapse — your verdict is consumed in-session by the main agent.
+   ```
+3. If the verdict surfaces issues, apply revisions with `synapse_update_experiment_plan({ experimentUuid, ... })`.
+4. `synapse_update_experiment_status({ experimentUuid, status: "pending_review" })` to push the draft into review.
+5. Present the self-review summary and the plan summary to the user in the terminal. Wait for a verbal answer.
+6. **On verbal approve:**
+   ```
+   synapse_review_experiment({
+     experimentUuid,
+     decision: "approved",
+     reviewNote: 'User verbally approved in terminal: "<exact words>"',
+   })
+   ```
+   That call atomically transitions to `pending_start`, writes the activity, and emits `task_assigned` so execution can begin.
+7. **On verbal reject:** summarize the user's revision request in second-person Chinese, including a quoted phrase from the user, and pass it as `reviewNote`:
+   ```
+   synapse_review_experiment({
+     experimentUuid,
+     decision: "rejected",
+     reviewNote: '用户口头要求修改：…（原话："…"）',
+   })
+   ```
+   The review tool writes the comment and emits `experiment_revision_requested` automatically — **do not** also call `synapse_add_comment`.
+8. After a reject, the experiment is back in `draft`. Revise per feedback, run self-review again, then resubmit to `pending_review`.
+9. **Full-auto mode** (set verbally via the `autonomy` skill, lives only in the current CC session): after step 4, skip steps 5–8 and immediately call `synapse_review_experiment` with the fixed full-auto template:
+   ```
+   reviewNote: 'Full-auto session authorized by <ownerName> at <ISO time>. Self-review pass: <key points>.'
+   ```
+   If self-review timed out or errored: `'Self-review skipped: <reason>.'`. Full-auto **never pauses** on advisory self-review output — it only exits on user-stop or hard external errors.
+
+The `synapse_review_experiment` tool requires `admin` or `pi_agent` role. To run verbal-approve flows on Claude Code, configure the CC agent with one of those roles.
+
 ## Foundational First Experiment
 
 If the project has no completed experiments yet, the first experiment is not a normal research run — it is the project's baseline infrastructure. Drive it through three bundled deliverables before any comparison work:
@@ -51,20 +97,20 @@ If the project has a repo, commit all three onto the base branch (or a per-exper
 
 1. `synapse_checkin()` — refresh identity and assignments
 2. Author or fetch the experiment
-   - New plan: `synapse_create_experiment(...)` (defaults to `pending_review`, or `status: "draft"` to keep editing)
+   - New plan: `synapse_create_experiment(...)` (defaults to `draft`; run a self-review sub-agent and revise before pushing to `pending_review` per the section below)
    - Existing assignment: `synapse_get_assigned_experiments()` then `synapse_get_experiment({ experimentUuid })`
 3. If drafting or revising: `synapse_update_experiment_status({ status: "draft", liveStatus: "writing" })` + `synapse_update_experiment_plan(...)`, then `synapse_update_experiment_status({ status: "pending_review" })`
 4. Before execution: `synapse_list_compute_nodes({ onlyAvailable: true, researchProjectUuid })`
 5. Reserve compute: optional `synapse_reserve_gpus(...)` or inline via `synapse_start_experiment({ gpuUuids })`
 6. `synapse_start_experiment({ experimentUuid, workingNotes })` — moves to `in_progress`
 7. If remote compute: `synapse_get_node_access_bundle({ experimentUuid, nodeUuid })`, write the returned `privateKeyPemBase64` to a local PEM, `chmod 600`, SSH with the returned host/user/port
-8. If repo-backed: `synapse_get_repo_access` → clone → branch from the experiment's base branch
+8. If repo-backed: `synapse_get_repo_access` → clone → branch from the experiment's base branch (commit + push back to this repo at the end is mandatory)
 9. Run the workload in a persistent remote shell (`tmux`/`screen`) with unbuffered output (`python -u …` or `PYTHONUNBUFFERED=1`) so logs never stall a tool call
 10. Report progress with `synapse_report_experiment_progress` at milestones — `phase` ∈ `setup` | `training` | `evaluation` | `analysis`; `liveStatus` ∈ `checking_resources` | `queuing` | `running`
 11. For long runs (>30 min), schedule periodic progress updates (cron on the remote node, or the main agent polling and calling `synapse_report_experiment_progress` on a timer) so the card never looks dead
 12. Commit code/artifacts to the experiment branch or base branch; capture the commit SHA
 13. Finish with `synapse_submit_experiment_results({ outcome, experimentResults, branch, commitSha })` — `outcome` ∈ `success` | `failure` | `inconclusive`; on failure include the error and partial results
-14. If the flow asks for a dedicated report document: `synapse_save_experiment_report({ experimentUuid, title, content })` — do **not** post a full report as a comment
+14. **Always** follow `synapse_submit_experiment_results` with `synapse_save_experiment_report({ experimentUuid, title, content })` — write a full markdown writeup (objective, methodology, results, analysis, charts where relevant). Do **not** post the report as a comment, and do **not** treat this step as optional even for `failure` / `inconclusive` runs
 15. If revising per reviewer feedback, read the full thread first with `synapse_get_comments({ targetType: "experiment", targetUuid })` before editing the plan
 
 ## Core Rules
@@ -72,6 +118,8 @@ If the project has a repo, commit all three onto the base branch (or a per-exper
 - **Never assume a server-local SSH key path exists.** Always fetch the access bundle and write the PEM locally.
 - **One independent run per experiment card.** Do not bundle comparison runs, ablations, or parameter sweeps into a single experiment — create multiple cards.
 - **Match the project description's language.** If the project brief is in Chinese, write the plan, progress, and report in Chinese.
+- **If the project is repo-backed, you must commit back.** Whenever `synapse_get_repo_access` returns a configured repo, all experiment code, configs, and meaningful artifacts must be committed and pushed to that repo (on the experiment branch or merged to base), and the resulting `branch` + `commitSha` must be passed to `synapse_submit_experiment_results`. Local-only runs without a commit are not acceptable when a repo exists.
+- **Always save an experiment report after submitting results.** Every `synapse_submit_experiment_results` call must be immediately followed by `synapse_save_experiment_report({ experimentUuid, title, content })` with a full markdown writeup. This applies to `success`, `failure`, and `inconclusive` outcomes alike.
 - **Split plan / execution / report tools.** Use `synapse_update_experiment_plan` for plan edits, `synapse_report_experiment_progress` for live status, `synapse_submit_experiment_results` for completion, and `synapse_save_experiment_report` for the dedicated report. Do not substitute with comments.
 - **Revision stays durable.** When a reviewer sends an experiment back, flip to `draft`, revise, then move it back to `pending_review`; leave a reply via `synapse_add_comment` using `@[name](actorType:uuid)` format to notify the reviewer.
 - **Failures are data.** An experiment that crashes or shows a regression is still a valid submission: set `outcome: "failure"` (or `"inconclusive"`) and write up what happened in `experimentResults` and the report.

package/dist/public/synapse-plugin/skills/sessions/SKILL.md

@@ -130,7 +130,9 @@ synapse_get_assigned_experiments({
 # For any experiment still in_progress, read its latest state
 synapse_get_experiment({ experimentUuid })
 
-# Once all have completed, synthesize / propose follow-ups
+# Once all have completed, synthesize. If this is the assigned autonomous-loop
+# agent, propose follow-ups; otherwise use synapse_create_experiment for
+# user-directed terminal work.
 synapse_propose_experiment({ researchProjectUuid, title, description })
 ```
 

package/dist/public/synapse-plugin/skills/setup/SKILL.md

@@ -30,13 +30,33 @@ This skill does not cover day-to-day research or experiment execution. Hand off
 ## Recommended Flow
 
 1. Get an API key from the Synapse **Agents** page.
-2. Put Synapse MCP config at project level in `.mcp.json`.
-3. Restart Claude Code if needed.
+2. Set `SYNAPSE_URL` and `SYNAPSE_API_KEY` **in one place** (see "Where the credentials live" below).
+3. Restart Claude Code so it reloads MCP config and re-evaluates env.
 4. Call `synapse_checkin()` and confirm expected roles/tools are visible.
 
-## Project-Level MCP Template
+The plugin already ships its own `.mcp.json` (at `public/synapse-plugin/.mcp.json` inside the plugin bundle), so you do **not** need to copy a `.mcp.json` into your project. Installing the plugin makes the MCP server available; the only thing you supply is the env values.
 
-The plugin ships a project-level template at `public/synapse-plugin/.mcp.json`. The expected content is:
+## Where The Credentials Live (Important)
+
+The plugin's bundled `.mcp.json` carries `${SYNAPSE_URL}` and `${SYNAPSE_API_KEY}` placeholders. Claude Code substitutes them at MCP-server-startup time from your env. You only put the real values in **one** location:
+
+- **User-level Claude Code settings** — `~/.claude/settings.json`'s `env` block. Best for personal use across projects.
+  ```json
+  {
+    "env": {
+      "SYNAPSE_URL": "http://localhost:3000",
+      "SYNAPSE_API_KEY": "syn_..."
+    }
+  }
+  ```
+- **Project-level Claude Code settings** — `<project>/.claude/settings.json`'s `env` block. Best when several teammates share a project but each needs their own key (use `.claude/settings.local.json` for personal values; never commit the key).
+- **Shell environment** — `export SYNAPSE_URL=...; export SYNAPSE_API_KEY=...` in your shell rc, before launching Claude Code. Ad-hoc only.
+
+The plugin's bash hooks (`SessionStart`, `PostToolUse`, etc.) also read the same two env variables, so a single env source covers both the MCP server and the hook scripts.
+
+## Plugin's Own `.mcp.json` (For Reference)
+
+You don't need to edit or copy this file — the plugin ships and loads it automatically:
 
 ```json
 {
@@ -52,6 +72,20 @@ The plugin ships a project-level template at `public/synapse-plugin/.mcp.json`.
 }
 ```
 
+If you have a strong reason to override (e.g. add `X-Synapse-Project` filter headers for one project), you can add a `.mcp.json` at your project root that defines a different `synapse` server entry — Claude Code project-level config takes precedence.
+
+## Roles That Matter
+
+Set the agent's roles on the **Agents** page based on what you expect Claude Code to do:
+
+- `pre_research` — paper search, literature reading.
+- `research` — research-question CRUD.
+- `experiment` — create/start/report/submit experiments, compute tools.
+- `report` — document and synthesis tools.
+- `admin` / `pi_agent` — needed if Claude Code should call `synapse_review_experiment` to carry the user's verbal approve / reject from the terminal into Synapse. Without one of these, `/api/experiments/<uuid>/review` returns 403.
+
+If the same Claude Code agent should both execute experiments and verbally-approve them, give it both `experiment` and `admin` (or `pi_agent`).
+
 ## Verification
 
 Use:
@@ -64,6 +98,7 @@ If the connection is wrong, check:
 - the key starts with `syn_`
 - `SYNAPSE_URL` is reachable
 - Claude Code has reloaded the MCP config
+- the env variables actually reach the MCP server process (`echo $SYNAPSE_URL` from the same shell that launches Claude Code)
 - the agent has the roles needed for the tools you expect to use
 
 ## Reference

package/dist/public/synapse-plugin/skills/synapse/SKILL.md

@@ -104,7 +104,8 @@ Each stage skill repeats this onboarding prompt from its own perspective when en
 | Documents and synthesis | `synapse_get_documents`, `synapse_get_document`, `synapse_save_project_synthesis` |
 | Literature and deep research | `synapse_search_papers`, `synapse_add_related_work`, `synapse_get_related_works`, `synapse_get_deep_research_report` |
 | Research questions | `synapse_get_research_question` and research-question mutation tools when roles allow |
-| Experiments | `synapse_get_assigned_experiments`, `synapse_get_experiment`, `synapse_start_experiment`, `synapse_report_experiment_progress`, `synapse_submit_experiment_results`, `synapse_propose_experiment` |
+| Experiments | `synapse_get_assigned_experiments`, `synapse_get_experiment`, `synapse_create_experiment`, `synapse_start_experiment`, `synapse_report_experiment_progress`, `synapse_submit_experiment_results`, `synapse_propose_experiment` (autonomous loop only) |
+| PI/Admin review | `synapse_review_experiment` |
 | Compute | `synapse_list_compute_nodes`, `synapse_reserve_gpus`, `synapse_get_node_access_bundle` |
 | Collaboration | `synapse_add_comment`, `synapse_get_comments`, `synapse_search_mentionables` |
 | Task cleanup | `synapse_complete_task` except where a task-specific save/submit tool already clears state |

package/dist/public/synapse-plugin/skills/synapse/references/00-common-tools.md

@@ -61,7 +61,7 @@ Requires the `experiment` tool family.
 | `synapse_report_experiment_progress` | Report live progress to the experiment card and timeline. Supports `liveStatus` such as `queuing`, `checking_resources`, or `running`. |
 | `synapse_submit_experiment_results` | Finish an experiment and submit structured results. |
 | `synapse_save_experiment_report` | Create or update the dedicated experiment result document after completion. |
-| `synapse_propose_experiment` | Propose the next experiment during autonomous loop execution. Human-review mode creates `pending_review`; full-auto mode creates `pending_start` and auto-assigns it back to the agent. |
+| `synapse_propose_experiment` | Autonomous-loop only: propose the next experiment when the caller is the assigned loop agent. Human-review mode creates `pending_review`; full-auto mode creates `pending_start` and auto-assigns it back to the agent. Use `synapse_create_experiment` for user-directed terminal work. |
 | `synapse_list_compute_nodes` | List pools, nodes, GPUs, and access details. |
 | `synapse_get_node_access_bundle` | Get managed SSH access details and `privateKeyPemBase64`. |
 | `synapse_sync_node_inventory` | Sync node instance metadata and GPU inventory. |
@@ -70,6 +70,43 @@ Requires the `experiment` tool family.
 
 ---
 
+## PI / Admin Review
+
+Requires `admin`, `pi`, or `pi_agent`.
+
+| Tool | Description |
+|------|-------------|
+| `synapse_review_experiment` | Approve a pending experiment into `pending_start` or reject it back to `draft`. Use this for Claude Code terminal review flows. |
+
+### `reviewNote` Formatting
+
+`synapse_review_experiment` records `reviewNote` in:
+- the activity entry,
+- the recipient notification,
+- and (on reject) a comment authored by the actor.
+
+The wording matters because the actor is the agent — `reviewNote` is what makes the human voice visible in audit. Use these formats:
+
+- **Verbal approve (Claude Code terminal):**
+  ```
+  reviewNote: 'User verbally approved in terminal: "<exact words from the user>"'
+  ```
+- **Verbal reject (Claude Code terminal):** summarize the user's revision request in second-person Chinese, including a quoted phrase. Example:
+  ```
+  reviewNote: '用户口头要求修改：把 batch size 改回 32（原话："那个 batch size 改回 32 试试"）'
+  ```
+  The tool writes the comment and emits `experiment_revision_requested` automatically — **do not** also call `synapse_add_comment`.
+- **Claude Code full-auto auto-approve:**
+  ```
+  reviewNote: 'Full-auto session authorized by <ownerName> at <ISO time>. Self-review pass: <key points>.'
+  ```
+  Or, if self-review failed:
+  ```
+  reviewNote: 'Full-auto session authorized by <ownerName> at <ISO time>. Self-review skipped: <reason>.'
+  ```
+
+---
+
 ## Literature And Related Works
 
 Usually requires `pre_research`.

package/dist/public/synapse-plugin/skills/synapse/references/01-setup.md

@@ -28,27 +28,44 @@ If you do not have an API key yet:
 
 ## 2. MCP Server Configuration
 
-Synapse MCP uses the HTTP Streamable transport. Place this in `.mcp.json` at the project root or globally at `~/.claude/.mcp.json`.
+Synapse MCP uses the HTTP Streamable transport. **Once the Synapse plugin is installed in Claude Code, you do not need to write your own `.mcp.json`** — the plugin bundles one (at `public/synapse-plugin/.mcp.json`) and Claude Code loads it automatically.
 
-The plugin bundle also ships the same template at `public/synapse-plugin/.mcp.json` so teams can copy a project-level config into place instead of rewriting it from scratch.
-
-Replace `<BASE_URL>` with the Synapse address (for example `https://synapse.example.com` or `http://localhost:3000`).
+The bundled file uses env placeholders:
 
 ```json
 {
   "mcpServers": {
     "synapse": {
       "type": "http",
-      "url": "<BASE_URL>/api/mcp",
+      "url": "${SYNAPSE_URL}/api/mcp",
       "headers": {
-        "Authorization": "Bearer <your-api-key>"
+        "Authorization": "Bearer ${SYNAPSE_API_KEY}"
       }
     }
   }
 }
 ```
 
-Restart Claude Code after configuration so MCP picks up the new server.
+You only have to supply the env values, in **one** place. Example via `~/.claude/settings.json`:
+
+```json
+{
+  "env": {
+    "SYNAPSE_URL": "http://localhost:3000",
+    "SYNAPSE_API_KEY": "syn_..."
+  }
+}
+```
+
+Other equally valid sources for those env values:
+- `<project>/.claude/settings.json`'s `env` block (project scope; per-developer values can go in `.claude/settings.local.json`).
+- Shell environment (`export SYNAPSE_URL=...; export SYNAPSE_API_KEY=...`) before launching Claude Code.
+
+The plugin's bash hooks read the same two variables, so one env source covers both the MCP server and the hook scripts.
+
+If you really do need to override the bundled MCP entry (e.g. to add `X-Synapse-Project` filter headers for one project), drop a project-root `.mcp.json` with a `synapse` entry — Claude Code project-level config takes precedence.
+
+Restart Claude Code after editing env values so MCP picks them up.
 
 ### Optional: Project Filtering
 
@@ -88,9 +105,10 @@ A successful response includes your agent identity, roles, current assignments,
 
 If it fails, check:
 - Is the API key correct and does it start with `syn_`?
-- Is the URL reachable?
-- Did you restart Claude Code?
-- Does the agent have the roles needed for the tools you expect to use (`pre_research`, `research`, `experiment`, `report`, `admin`)?
+- Is the URL reachable from the machine running Claude Code?
+- Did you restart Claude Code after editing `.mcp.json` or `settings.json`?
+- Are the env variables actually visible to the MCP server process? `echo $SYNAPSE_URL` from the shell that launches Claude Code should print the value.
+- Does the agent have the roles needed for the tools you expect to use (`pre_research`, `research`, `experiment`, `report`, `admin`, `pi_agent`)? `synapse_review_experiment` requires `admin` or `pi_agent` specifically.
 
 ---
 

package/dist/public/synapse-plugin/skills/synapse/references/03-experiment-workflow.md

@@ -208,7 +208,7 @@ This is the detailed flow for moving an experiment through `in_progress` to `com
 
 9. **Monitoring — short runs** (a few minutes): skip the cron, report progress inline at setup / mid-training / evaluation / analysis transitions.
 
-10. **Commit code and artifacts** — commit configs, scripts, and meaningful artifacts to the experiment branch (or base branch) and capture the commit SHA to include in the submission.
+10. **Commit code and artifacts** — if `synapse_get_repo_access` shows the project is repo-backed, you **must** commit configs, scripts, and meaningful artifacts to the experiment branch (or base branch) **and push to the configured repo**. Capture the commit SHA so it can be passed to `synapse_submit_experiment_results` as `experimentResults.commit` (and `branch`). Local-only runs that never push back are not acceptable when a repo is configured.
 
 11. **Submit results**
 
@@ -227,7 +227,7 @@ This is the detailed flow for moving an experiment through `in_progress` to `com
 
     `outcome` is optional, typically `success`, `failure`, or `inconclusive`. Submitting moves the experiment to `completed`, refreshes the experiment result document, and triggers the project synthesis refresh.
 
-12. **Save the dedicated experiment report** — when the flow asks for a full writeup:
+12. **Save the dedicated experiment report** — every submission must be immediately followed by a markdown report. This is required for `success`, `failure`, and `inconclusive` outcomes:
 
     ```text
     synapse_save_experiment_report({
@@ -237,7 +237,7 @@ This is the detailed flow for moving an experiment through `in_progress` to `com
     })
     ```
 
-    Use python + a plotting library to generate charts and embed them in the markdown where they help. Do **not** post the report as a comment — always use `synapse_save_experiment_report` so the dedicated result document exists.
+    Use python + a plotting library to generate charts and embed them in the markdown where they help. Do **not** post the report as a comment — always use `synapse_save_experiment_report` so the dedicated result document exists. The plugin's `PostToolUse` hook on `synapse_submit_experiment_results` injects a reminder, but you should treat this step as part of the submit flow, not as something to wait for the hook to nag about.
 
 13. **Match the project description's language** — if the project brief is in Chinese, write plan, progress messages, and report in Chinese.
 
@@ -313,7 +313,7 @@ When a reviewer sends `pending_review` back to `draft`:
 8. Run workload in tmux + unbuffered python
 9. `synapse_report_experiment_progress()` at milestones
 10. `synapse_submit_experiment_results()` — success, failure, or inconclusive
-11. `synapse_save_experiment_report()` if a dedicated report is required
+11. `synapse_save_experiment_report()` — **always** runs immediately after submit, regardless of outcome
 12. `synapse_add_comment()` for durable findings and mention the reviewer
 
 For parallel multi-experiment dispatch (main agent orchestrates, sub-agents execute), see **[05-session-sub-agent.md](05-session-sub-agent.md)**.

package/dist/public/synapse-plugin/skills/synapse/references/05-session-sub-agent.md

@@ -184,7 +184,9 @@ synapse_get_assigned_experiments({
 # For any experiment still in_progress, read its latest state:
 synapse_get_experiment({ experimentUuid })
 
-# Once all have completed, synthesize and propose follow-ups:
+# Once all have completed, synthesize. If this is the assigned autonomous-loop
+# agent, propose follow-ups; otherwise use synapse_create_experiment for
+# user-directed terminal work.
 synapse_save_project_synthesis({ researchProjectUuid, title, content })
 synapse_propose_experiment({ researchProjectUuid, title, description })
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapse-research/synapse",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "Synapse — AI Research Orchestration Platform (zero-dependency local mode)",
   "license": "AGPL-3.0",
   "bin": {