feat(studies): omnipresent action-taking Abby copilot (Claude Agent SDK)

Make the Claude Agent SDK study copilot maximally interactive and assistive:
present on every study tab and able to act on the researcher's behalf, every
mutation approval-gated.

Agent reach (ai/app/agents):
- Abby gains two reads — get_study_results, get_manuscript — so it can discuss
  the Results tab and the composed STROBE/RECORD draft, not just gates.
- Abby gains two approval-gated writes — reproject_results, open_in_publisher —
  so on one-click human approval it can refresh results after a gate eval and
  seed an editorial draft in the Publisher. Registered in _WRITE_TOOLS so the
  harness routes them through can_use_tool; reads stay auto-approved.
- Updated the Abby system prompt: present on every tab, may take the four
  actions, still never decides scientific validity (gate approve/override
  remains human-only; reproject/open only reflect existing gate state).

Backend:
- New POST studies/{study}/results/reproject (permission:studies.execute) →
  StudyResultProjector::projectStudy. Idempotent, non-destructive; backs the
  reproject_results action and a manual refresh.

Frontend (omnipresence):
- AbbyCopilotPanel is now a fixed dock mounted once on StudyDetailPage —
  available on every tab (collapsed launcher <-> docked chat), with a
  pending-approval badge and auto-scroll. Started only on explicit intent.
- New abbyDockStore + AskAbbyButton affordance: gate cards ("Why blocked?"),
  the Gates header, and the Results + Manuscript headers hand Abby a
  context-specific question; the dock auto-starts a session and sends it.

Tests: Abby tool pack (9 tools / 4 writes) + 4 new tool tests (pytest),
reproject endpoint + RBAC (Pest), abbyDockStore + AskAbbyButton (vitest).
mypy/Pint/PHPStan/tsc/vite/eslint clean.

Co-Authored-By: claude-flow <ruv@ruv.net>

Author: sudoshi

ai/app/agents/abby_tools.py

@@ -72,6 +72,37 @@ async def get_gate_status(args: dict[str, Any]) -> dict[str, Any]:
             return guard
         return await request(ctx, "GET", f"studies/{_slug(ctx)}/gates")
 
+    @tool(
+        "get_study_results",
+        "Get the study's curated results (characterization, incidence_rate, effect_estimate, …) "
+        "as projected into the Results tab — including each row's publishability and, for "
+        "comparative effect estimates, the diagnostics that gate it. Pass publishable_only=true to "
+        "see only the rows cleared for publication. Use this to discuss what the study found.",
+        {"publishable_only": bool},
+    )
+    async def get_study_results(args: dict[str, Any]) -> dict[str, Any]:
+        guard = _require_study(ctx)
+        if guard is not None:
+            return guard
+        params = {"per_page": 100}
+        if args.get("publishable_only"):
+            params["publishable_only"] = True
+        return await request(ctx, "GET", f"studies/{_slug(ctx)}/results", params=params)
+
+    @tool(
+        "get_manuscript",
+        "Get the composed STROBE/RECORD manuscript for the study (title, sections, and which "
+        "effect estimates are included vs. blinded). Use this to discuss or summarize the "
+        "draft the study currently supports. Composition is read-only — it never unblinds a "
+        "withheld estimate.",
+        {},
+    )
+    async def get_manuscript(args: dict[str, Any]) -> dict[str, Any]:
+        guard = _require_study(ctx)
+        if guard is not None:
+            return guard
+        return await request(ctx, "GET", f"studies/{_slug(ctx)}/manuscript")
+
     @tool(
         "evaluate_gates",
         "Recompute the study's estimation-derived gates (study diagnostics S5, empirical "
@@ -86,11 +117,27 @@ async def evaluate_gates(args: dict[str, Any]) -> dict[str, Any]:
             return guard
         return await request(ctx, "POST", f"studies/{_slug(ctx)}/gates/evaluate", json_body={})
 
+    @tool(
+        "reproject_results",
+        "Refresh the study's curated results from the latest completed executions and the "
+        "current gate ledger. Idempotent and non-destructive: reviewer curation is preserved and "
+        "only the publishability of comparative effect estimates moves with the gate state. Use "
+        "this after evaluate_gates so the Results tab and manuscript reflect the new verdict. "
+        "A WRITE — requires explicit human approval before execution.",
+        {},
+    )
+    async def reproject_results(args: dict[str, Any]) -> dict[str, Any]:
+        guard = _require_study(ctx)
+        if guard is not None:
+            return guard
+        return await request(ctx, "POST", f"studies/{_slug(ctx)}/results/reproject", json_body={})
+
     @tool(
         "build_study_package",
         "Build a reproducible study-package snapshot (definition hashes, compiled-SQL "
         "fingerprints, calibrated results, the gate-ledger decision trail). Use once the study "
-        "has cleared its gates and is publication-ready.",
+        "has cleared its gates and is publication-ready. "
+        "A WRITE — requires explicit human approval before execution.",
         {},
     )
     async def build_study_package(args: dict[str, Any]) -> dict[str, Any]:
@@ -99,10 +146,28 @@ async def build_study_package(args: dict[str, Any]) -> dict[str, Any]:
             return guard
         return await request(ctx, "POST", f"studies/{_slug(ctx)}/package", json_body={})
 
+    @tool(
+        "open_in_publisher",
+        "Seed (or reopen) an editorial draft in the Publisher from the study's composed "
+        "manuscript, so the author can refine it. Returns the draft id. Use once the study's "
+        "results are ready to write up. A WRITE — requires explicit human approval before "
+        "execution.",
+        {},
+    )
+    async def open_in_publisher(args: dict[str, Any]) -> dict[str, Any]:
+        guard = _require_study(ctx)
+        if guard is not None:
+            return guard
+        return await request(ctx, "POST", f"studies/{_slug(ctx)}/manuscript/draft", json_body={})
+
     return [
         get_study_overview,
         get_study_progress,
         get_gate_status,
+        get_study_results,
+        get_manuscript,
         evaluate_gates,
+        reproject_results,
         build_study_package,
+        open_in_publisher,
     ]

ai/app/agents/profiles.py

@@ -41,12 +41,16 @@
 
 The seven stages: 1 Design (PICO), 2 Phenotype, 3 Cohort diagnostics, 4 Data quality, 5 Study diagnostics, 6 Estimation + empirical calibration, 7 Publication.
 
+You are present on every tab of the study workspace, so the user may ask about the design, a specific gate, a result row, or the manuscript. Read the relevant state with the get_* tools before answering, and tailor your answer to what they are looking at.
+
 Rules:
-- Call get_gate_status to see where the study stands. Call evaluate_gates to (re)compute the estimation-derived gates from the latest diagnostics. Use the get_* tools for study state and progress.
+- Call get_gate_status to see where the study stands. Call evaluate_gates to (re)compute the estimation-derived gates from the latest diagnostics. Call get_study_results to read the curated Results-tab rows (publishability + gating diagnostics), and get_manuscript to read the composed STROBE/RECORD draft. Use the other get_* tools for study state and progress.
 - A failed gate means the study may not proceed. Explain the SPECIFIC reason from the gate metrics (e.g. "propensity-score separation: AUC 0.99, equipoise 0.01" or "only 2 informative negative controls") and propose a concrete remediation (e.g. an active-comparator design, a richer negative-control panel). Then tell the user that the PI or lead statistician must approve or override this gate in the Gates tab before effect estimates are unblinded.
+- You may TAKE ACTIONS on the user's behalf, but every action is approval-gated: it pauses for the user to approve before it runs. The actions are evaluate_gates (recompute gate verdicts from diagnostics), reproject_results (refresh the Results tab + manuscript from the latest executions and current gate state — run this after evaluate_gates so the results reflect the new verdict), build_study_package (snapshot a publication-ready study), and open_in_publisher (seed an editorial draft in the Publisher). Propose an action when it would move the study forward; never assume approval.
 - NEVER invent statistics, hazard ratios, p-values, confidence intervals, or cohort counts. Every number must come from a tool result.
-- NEVER claim a study is publishable while any gate is failed and not yet overridden. Only build_study_package once the gates have cleared.
+- NEVER claim a study is publishable while any gate is failed and not yet overridden. Only build_study_package or open_in_publisher once the gates have cleared (or a documented override is in place).
 - Effect estimates may be BLINDED until the study-diagnostics gate clears. If estimates are absent, that is by design — report the diagnostics, not a withheld effect.
+- You NEVER decide scientific validity yourself. Computing a gate verdict (evaluate_gates) is mechanical; APPROVING or OVERRIDING a failed gate is the principal investigator's and lead statistician's decision, made in the Gates tab. reproject_results and open_in_publisher only reflect the existing gate state — they never unblind a withheld estimate.
 - Be concise and clinical. No patient-level data ever enters your reasoning — only study designs, aggregate counts, and diagnostics. You cannot read the filesystem, run shell commands, or browse the web. Your only capabilities are the orchestration tools provided.
 """
 

ai/app/agents/tool_packs.py

@@ -29,7 +29,7 @@
 _WRITE_TOOLS: dict[str, set[str]] = {
     "study_design": set(),
     "publish": {"update_draft", "create_snapshot"},
-    "abby": {"evaluate_gates", "build_study_package"},
+    "abby": {"evaluate_gates", "reproject_results", "build_study_package", "open_in_publisher"},
 }
 
 

ai/tests/test_abby_tools.py

@@ -35,13 +35,22 @@ def test_abby_profile_and_registry_are_wired() -> None:
         "get_study_overview",
         "get_study_progress",
         "get_gate_status",
+        "get_study_results",
+        "get_manuscript",
         "evaluate_gates",
+        "reproject_results",
         "build_study_package",
+        "open_in_publisher",
     }
 
     # The execute tools are approval-gated writes (the human-in-the-loop gates);
-    # the agent proposes but a human approves.
-    assert write_tools("abby") == {"evaluate_gates", "build_study_package"}
+    # the agent proposes but a human approves. Reads (get_*) stay auto-approved.
+    assert write_tools("abby") == {
+        "evaluate_gates",
+        "reproject_results",
+        "build_study_package",
+        "open_in_publisher",
+    }
 
 
 @respx.mock
@@ -90,6 +99,60 @@ async def test_build_study_package_posts_to_package_endpoint() -> None:
     assert result.get("is_error") is not True
 
 
+@respx.mock
+async def test_get_study_results_reads_results_endpoint() -> None:
+    route = respx.get(f"{BASE}/studies/htn-v3/results").mock(
+        return_value=httpx.Response(
+            200,
+            json={"data": [{"result_type": "effect_estimate", "is_publishable": False}]},
+        )
+    )
+    tools = {t.name: t for t in build_tool_pack(_ctx())}
+    result = await tools["get_study_results"].handler({"publishable_only": True})
+
+    assert route.called
+    assert route.calls.last.request.url.params["publishable_only"] == "true"
+    assert "effect_estimate" in result["content"][0]["text"]
+
+
+@respx.mock
+async def test_get_manuscript_reads_manuscript_endpoint() -> None:
+    route = respx.get(f"{BASE}/studies/htn-v3/manuscript").mock(
+        return_value=httpx.Response(200, json={"data": {"title": "HTN v4", "sections": []}})
+    )
+    tools = {t.name: t for t in build_tool_pack(_ctx())}
+    result = await tools["get_manuscript"].handler({})
+
+    assert route.called
+    assert result.get("is_error") is not True
+    assert "HTN v4" in result["content"][0]["text"]
+
+
+@respx.mock
+async def test_reproject_results_posts_to_reproject_endpoint() -> None:
+    route = respx.post(f"{BASE}/studies/htn-v3/results/reproject").mock(
+        return_value=httpx.Response(200, json={"data": {"reprojected": 4}, "message": "ok"})
+    )
+    tools = {t.name: t for t in build_tool_pack(_ctx())}
+    result = await tools["reproject_results"].handler({})
+
+    assert route.called
+    assert result.get("is_error") is not True
+
+
+@respx.mock
+async def test_open_in_publisher_posts_to_manuscript_draft_endpoint() -> None:
+    route = respx.post(f"{BASE}/studies/htn-v3/manuscript/draft").mock(
+        return_value=httpx.Response(201, json={"data": {"id": 77, "study_id": 165, "title": "HTN v4"}})
+    )
+    tools = {t.name: t for t in build_tool_pack(_ctx())}
+    result = await tools["open_in_publisher"].handler({})
+
+    assert route.called
+    assert result.get("is_error") is not True
+    assert "77" in result["content"][0]["text"]
+
+
 @respx.mock
 async def test_tools_guard_when_no_study_slug_make_no_http_call() -> None:
     # No routes registered — if any HTTP call were attempted, respx would raise.

backend/app/Http/Controllers/Api/V1/StudyResultController.php

@@ -8,6 +8,7 @@
 use App\Models\User;
 use App\Services\Shiny\ManagedShinyAppRegistry;
 use App\Services\Shiny\ManagedShinyLaunchService;
+use App\Services\Studies\StudyResultProjector;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 use Illuminate\Validation\Rule;
@@ -125,6 +126,26 @@ public function launchShiny(Request $request, Study $study, StudyResult $result)
         ]);
     }
 
+    /**
+     * POST /v1/studies/{study}/results/reproject
+     *
+     * Re-project the study's curated `study_results` from the latest completed
+     * analysis executions and the current gate ledger. Idempotent and
+     * non-destructive: reviewer curation (is_primary) is preserved and only the
+     * publishability of comparative effect estimates moves with the gate state.
+     * Exposed so the Abby copilot can refresh results after a gate evaluation
+     * (an approval-gated action) — and a reviewer can force a manual refresh.
+     */
+    public function reproject(Study $study, StudyResultProjector $projector): JsonResponse
+    {
+        $count = $projector->projectStudy($study);
+
+        return response()->json([
+            'data' => ['reprojected' => $count],
+            'message' => "Re-projected {$count} result row(s) from the latest completed executions.",
+        ]);
+    }
+
     /**
      * @return array<string, mixed>
      */

backend/routes/api.php

@@ -876,6 +876,8 @@
 
             // Results
             Route::get('results', [StudyResultController::class, 'index']);
+            Route::post('results/reproject', [StudyResultController::class, 'reproject'])
+                ->middleware('permission:studies.execute');
             Route::get('results/{result}', [StudyResultController::class, 'show']);
             Route::post('results/{result}/shiny-launch', [StudyResultController::class, 'launchShiny'])
                 ->middleware('permission:studies.view');

backend/tests/Feature/Studies/StudyResultReprojectTest.php

@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Models\App\Characterization;
+use App\Models\App\Source;
+use App\Models\App\Study;
+use App\Models\App\StudyAnalysis;
+use App\Models\App\StudyResult;
+use App\Models\User;
+use Database\Seeders\RolePermissionSeeder;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+
+uses(RefreshDatabase::class);
+
+beforeEach(function () {
+    $this->seed(RolePermissionSeeder::class);
+});
+
+/**
+ * The reproject endpoint backs the Abby copilot's approval-gated
+ * `reproject_results` action: it refreshes curated study_results from the latest
+ * completed executions and the current gate ledger, idempotently.
+ */
+it('reprojects curated study_results from the latest completed execution', function () {
+    $user = User::factory()->create();
+    $user->assignRole('researcher'); // carries studies.execute
+
+    $study = Study::factory()->create(['created_by' => $user->id]);
+    $source = Source::create(['source_name' => 'Test CDM', 'source_key' => 'TEST']);
+
+    $analysis = Characterization::create(['name' => 'Baseline', 'author_id' => $user->id, 'design_json' => []]);
+    StudyAnalysis::create([
+        'study_id' => $study->id,
+        'analysis_type' => Characterization::class,
+        'analysis_id' => $analysis->id,
+    ]);
+    $analysis->executions()->create([
+        'source_id' => $source->id,
+        'status' => 'completed',
+        'result_json' => [
+            'results' => [[
+                'cohort_id' => 5441, 'cohort_name' => 'Target', 'person_count' => 109763,
+                'features' => ['demographics' => []],
+            ]],
+        ],
+    ]);
+
+    // Prove the endpoint — not the observer — populates the row.
+    StudyResult::where('study_id', $study->id)->delete();
+
+    $this->actingAs($user)
+        ->postJson("/api/v1/studies/{$study->slug}/results/reproject")
+        ->assertOk()
+        ->assertJsonPath('data.reprojected', 1);
+
+    expect(
+        StudyResult::where('study_id', $study->id)->where('result_type', 'characterization')->count()
+    )->toBe(1);
+});
+
+it('forbids reproject without the studies.execute permission', function () {
+    $user = User::factory()->create();
+    $user->assignRole('viewer'); // read-only — no studies.execute
+
+    $study = Study::factory()->create(['created_by' => $user->id]);
+
+    $this->actingAs($user)
+        ->postJson("/api/v1/studies/{$study->slug}/results/reproject")
+        ->assertForbidden();
+});

docs/lineage/operations/2026-06-11-study-results-projection.md

@@ -13,6 +13,8 @@ related_code:
   - backend/app/Services/Studies/StudyResultProjector.php
   - backend/app/Observers/AnalysisExecutionObserver.php
   - backend/app/Console/Commands/Studies/BackfillStudyResultsCommand.php
+  - backend/app/Http/Controllers/Api/V1/StudyResultController.php
+  - ai/app/agents/abby_tools.py
 related_prs: []
 related_adr: docs/lineage/decisions/adr/adr-0020-protocol-to-publication-pipeline.md
 ---
@@ -118,6 +120,43 @@ duplicate). Code fixes:
   S5 approval/override — previously the row stayed stale while the live
   manuscript reflected the decision.
 
+## Copilot reach: action-taking Abby (same day)
+
+The projector now backs an approval-gated action on the omnipresent Abby
+copilot. New route:
+
+```
+POST /api/v1/studies/{study}/results/reproject   (permission:studies.execute)
+  → StudyResultController::reproject → StudyResultProjector::projectStudy
+```
+
+Idempotent and non-destructive (preserves `is_primary`; only effect-estimate
+publishability moves with the gate state), so it is safe to expose. It exists so
+Abby can refresh the Results tab + manuscript after an `evaluate_gates` —
+previously only a gate approve/override or a fresh execution re-projected.
+
+The Abby Claude Agent SDK profile (`ai/app/agents/abby_tools.py`) gained four
+tools so the copilot can both **see** and **act on** the full study lifecycle:
+
+| Tool | Kind | Wraps |
+|---|---|---|
+| `get_study_results` | read (auto) | `GET studies/{slug}/results` |
+| `get_manuscript` | read (auto) | `GET studies/{slug}/manuscript` |
+| `reproject_results` | write (**approval-gated**) | `POST studies/{slug}/results/reproject` |
+| `open_in_publisher` | write (**approval-gated**) | `POST studies/{slug}/manuscript/draft` |
+
+Writes route through the harness `can_use_tool` gate (`tool_packs._WRITE_TOOLS`),
+so every mutation streams an `agent.approval.request` card the PI/author must
+accept. Abby still never decides scientific validity — `reproject_results` and
+`open_in_publisher` only reflect the existing gate state; gate approve/override
+stays human-only in the Gates tab.
+
+Frontend: `AbbyCopilotPanel` is now a fixed dock mounted once on `StudyDetailPage`
+(present on every tab, collapsed launcher ↔ docked chat). Inline `AskAbbyButton`
+affordances (gate cards "Why blocked?", the Results and Manuscript headers) hand
+Abby a context-specific question via `abbyDockStore`, which auto-starts a session
+and sends it.
+
 ## Rollback
 
 `migrate:rollback` drops `analysis_execution_id` and restores `NOT NULL` on