@piagent/platform 1.9.3 → 1.10.0

package/docs-site/en/permissions.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.9.3 docs · EN</span>
+        <span class="pill"><span class="pill-dot"></span>v1.10.0 docs · EN</span>
         <nav class="language-switch" aria-label="Language">
           <a class="language-option" href="/permissions" hreflang="vi" lang="vi">VI</a>
           <a class="language-option current" href="/en/permissions" hreflang="en" lang="en" aria-current="true">EN</a>

package/docs-site/en/profiles.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.9.3 docs · EN</span>
+        <span class="pill"><span class="pill-dot"></span>v1.10.0 docs · EN</span>
         <nav class="language-switch" aria-label="Language">
           <a class="language-option" href="/profiles" hreflang="vi" lang="vi">VI</a>
           <a class="language-option current" href="/en/profiles" hreflang="en" lang="en" aria-current="true">EN</a>

package/docs-site/en/quickstart.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.9.3 docs · EN</span>
+        <span class="pill"><span class="pill-dot"></span>v1.10.0 docs · EN</span>
         <nav class="language-switch" aria-label="Language">
           <a class="language-option" href="/quickstart" hreflang="vi" lang="vi">VI</a>
           <a class="language-option current" href="/en/quickstart" hreflang="en" lang="en" aria-current="true">EN</a>

package/docs-site/en/runtime.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.9.3 docs · EN</span>
+        <span class="pill"><span class="pill-dot"></span>v1.10.0 docs · EN</span>
         <nav class="language-switch" aria-label="Language">
           <a class="language-option" href="/runtime" hreflang="vi" lang="vi">VI</a>
           <a class="language-option current" href="/en/runtime" hreflang="en" lang="en" aria-current="true">EN</a>

package/docs-site/en/scope.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.9.3 docs · EN</span>
+        <span class="pill"><span class="pill-dot"></span>v1.10.0 docs · EN</span>
         <nav class="language-switch" aria-label="Language">
           <a class="language-option" href="/scope" hreflang="vi" lang="vi">VI</a>
           <a class="language-option current" href="/en/scope" hreflang="en" lang="en" aria-current="true">EN</a>

package/docs-site/en/security.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.9.3 docs · EN</span>
+        <span class="pill"><span class="pill-dot"></span>v1.10.0 docs · EN</span>
         <nav class="language-switch" aria-label="Language">
           <a class="language-option" href="/security" hreflang="vi" lang="vi">VI</a>
           <a class="language-option current" href="/en/security" hreflang="en" lang="en" aria-current="true">EN</a>

package/docs-site/en/team.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.9.3 docs · EN</span>
+        <span class="pill"><span class="pill-dot"></span>v1.10.0 docs · EN</span>
         <nav class="language-switch" aria-label="Language">
           <a class="language-option" href="/team" hreflang="vi" lang="vi">VI</a>
           <a class="language-option current" href="/en/team" hreflang="en" lang="en" aria-current="true">EN</a>

package/docs-site/en/whats-new.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.9.3 docs · EN</span>
+        <span class="pill"><span class="pill-dot"></span>v1.10.0 docs · EN</span>
         <nav class="language-switch" aria-label="Language">
           <a class="language-option" href="/whats-new" hreflang="vi" lang="vi">VI</a>
           <a class="language-option current" href="/en/whats-new" hreflang="en" lang="en" aria-current="true">EN</a>
@@ -103,6 +103,17 @@
               <h1>1.9.0: ask in plain language, the team's Harness checks</h1>
               <p>The task contract and workflow commands are gone. Company mode asks for checks and a review on its own; Stop, network commands on approval and clearer approval cards.</p>
             </div>
+<section class="section">
+  <p class="section-kicker">v1.10.0 · 2026-10-05</p>
+  <h2 id="v1-10-0">The main agent asks when it is unsure, and subagents may object to a brief</h2>
+  <p class="section-lead">When a request leaves a decision open, the main agent asks you with a card of numbered choices instead of guessing. A subagent shows its evidence when a brief drifts from the request, and a second disagreement is yours to decide. Used-up quota or a very large patch no longer stops the work.</p>
+  <div class="grid cols-3">
+    <article class="card"><h3 id="ask-user">Questions with choices</h3><p>1–4 questions, each with 2–4 numbered choices, always "Other" in your own words and "Let the agent decide". Press a number to choose, Enter to send. Stop while it waits, and on "continue" the agent asks again instead of choosing for you.</p></article>
+    <article class="card"><h3 id="objections">Subagents object to a brief</h3><p>A subagent reads your request verbatim and the plan above its brief. When the brief is wrong or drifts from the request it shows its evidence, and the main agent has to answer. A second disagreement marks the conversation "needs your decision".</p></article>
+    <article class="card"><h3 id="fallback">Work goes on when quota runs out</h3><p>A subagent whose quota is used up, or whose account rests, starts again on the Harness fallback model. A patch over 120 KB is reviewed in parts and the findings merge.</p></article>
+  </div>
+</section>
+
 <section class="section">
   <p class="section-kicker">v1.9.3 · 2026-10-03</p>
   <h2 id="v1-9-3">Typing Vietnamese never sends by mistake, and subagents read leaner pages</h2>

package/docs-site/en/workflows.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.9.3 docs · EN</span>
+        <span class="pill"><span class="pill-dot"></span>v1.10.0 docs · EN</span>
         <nav class="language-switch" aria-label="Language">
           <a class="language-option" href="/workflows" hreflang="vi" lang="vi">VI</a>
           <a class="language-option current" href="/en/workflows" hreflang="en" lang="en" aria-current="true">EN</a>

package/docs-site/index.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.9.3 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.10.0 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/" hreflang="en" lang="en">EN</a>
@@ -93,7 +93,7 @@
       <main>
         <div class="content-shell" data-article>
 <section class="hero">
-  <p class="eyebrow">Piagent 1.9.3</p>
+  <p class="eyebrow">Piagent 1.10.0</p>
   <h1>Coding agent cho cả team, kiểm tra từng bước.</h1>
   <p>
     Một dashboard cho Terminal và trình duyệt. Dùng model bằng tài khoản của bạn, hoặc model của công ty qua Agent Watch và Agent Studio. Guard kiểm tra từng tool call; ở chế độ công ty, Harness của team tự yêu cầu chạy check, cho subagent review và báo kết quả ngay dưới câu trả lời.
@@ -107,7 +107,7 @@
   <div class="hero-actions">
     <a class="button primary" href="/quickstart">Bắt đầu</a>
     <a class="button" href="/ecosystem">Hệ sinh thái</a>
-    <a class="button" href="/whats-new">Có gì mới trong 1.9.3</a>
+    <a class="button" href="/whats-new">Có gì mới trong 1.10.0</a>
     <a class="button" href="/commands">Xem command</a>
   </div>
 </section>
@@ -183,9 +183,9 @@ piagent-setup</code></pre>
   <h2 id="bat-dau-tu-dau">Bắt đầu từ đâu</h2>
   <div class="card-grid">
     <a class="doc-card" href="/whats-new">
-      <span class="card-kicker">Bản 1.9.3</span>
+      <span class="card-kicker">Bản 1.10.0</span>
       <h3>Có gì mới</h3>
-      <p>Gõ tiếng Việt không gửi nhầm, subagent đọc trang gọn hơn; ở 1.9.2: việc trên web do subagent nghiên cứu làm, khung chat không còn giật.</p>
+      <p>Main agent hỏi lại khi chưa rõ, subagent được phản biện brief; ở 1.9.3: gõ tiếng Việt không gửi nhầm, subagent đọc trang gọn hơn.</p>
     </a>
     <a class="doc-card" href="/ecosystem">
       <span class="card-kicker">Get started</span>

package/docs-site/mcp-approval.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.9.3 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.10.0 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/mcp-approval" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/mcp-approval" hreflang="en" lang="en">EN</a>

package/docs-site/mcp-auth.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.9.3 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.10.0 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/mcp-auth" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/mcp-auth" hreflang="en" lang="en">EN</a>

package/docs-site/mcp-servers.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.9.3 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.10.0 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/mcp-servers" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/mcp-servers" hreflang="en" lang="en">EN</a>

package/docs-site/mcp.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.9.3 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.10.0 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/mcp" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/mcp" hreflang="en" lang="en">EN</a>

package/docs-site/permissions.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.9.3 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.10.0 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/permissions" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/permissions" hreflang="en" lang="en">EN</a>

package/docs-site/profiles.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.9.3 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.10.0 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/profiles" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/profiles" hreflang="en" lang="en">EN</a>

package/docs-site/quickstart.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.9.3 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.10.0 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/quickstart" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/quickstart" hreflang="en" lang="en">EN</a>

package/docs-site/runtime.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.9.3 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.10.0 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/runtime" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/runtime" hreflang="en" lang="en">EN</a>

package/docs-site/scope.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.9.3 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.10.0 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/scope" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/scope" hreflang="en" lang="en">EN</a>

package/docs-site/security.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.9.3 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.10.0 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/security" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/security" hreflang="en" lang="en">EN</a>

package/docs-site/team.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.9.3 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.10.0 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/team" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/team" hreflang="en" lang="en">EN</a>

package/docs-site/whats-new.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.9.3 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.10.0 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/whats-new" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/whats-new" hreflang="en" lang="en">EN</a>
@@ -103,6 +103,17 @@
               <h1>Bản 1.9.0: nói việc bằng lời, Harness của team kiểm tra</h1>
               <p>Bỏ task contract và lệnh workflow. Chế độ công ty tự yêu cầu check và review; nút Dừng, lệnh có mạng theo lần duyệt và thẻ duyệt dễ đọc hơn.</p>
             </div>
+<section class="section">
+  <p class="section-kicker">v1.10.0 · 2026-10-05</p>
+  <h2 id="v1-10-0">Main agent hỏi lại khi chưa rõ, subagent được phản biện brief</h2>
+  <p class="section-lead">Khi yêu cầu còn để ngỏ một quyết định, main agent hỏi bạn bằng thẻ câu hỏi có lựa chọn đánh số thay vì đoán. Subagent được nêu bằng chứng khi brief lệch yêu cầu, và bất đồng lần hai thì bạn quyết. Hết quota hay patch quá lớn không còn làm dừng việc.</p>
+  <div class="grid cols-3">
+    <article class="card"><h3 id="ask-user">Hỏi lại bằng lựa chọn</h3><p>1–4 câu hỏi, mỗi câu 2–4 lựa chọn đánh số, luôn có "Khác" để tự nhập và "Để agent tự quyết". Bấm số để chọn, Enter để gửi. Bấm Dừng giữa chừng thì khi "tiếp tục", agent hỏi lại chứ không chọn thay bạn.</p></article>
+    <article class="card"><h3 id="objections">Subagent phản biện brief</h3><p>Subagent đọc nguyên văn yêu cầu và plan trước brief. Brief sai hoặc lệch yêu cầu thì subagent nêu bằng chứng và main agent phải trả lời. Bất đồng lần hai, hội thoại ghi "Cần bạn quyết".</p></article>
+    <article class="card"><h3 id="fallback">Chạy tiếp khi hết quota</h3><p>Subagent hết quota hoặc tài khoản đang nghỉ sẽ chạy lại trên model dự phòng của Harness. Patch trên 120 KB được review theo từng phần rồi gộp findings.</p></article>
+  </div>
+</section>
+
 <section class="section">
   <p class="section-kicker">v1.9.3 · 2026-10-03</p>
   <h2 id="v1-9-3">Gõ tiếng Việt không gửi nhầm, subagent đọc trang gọn hơn</h2>

package/docs-site/workflows.html

@@ -30,7 +30,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.9.3 docs · VI</span>
+        <span class="pill"><span class="pill-dot"></span>v1.10.0 docs · VI</span>
         <nav class="language-switch" aria-label="Ngôn ngữ">
           <a class="language-option current" href="/workflows" hreflang="vi" lang="vi" aria-current="true">VI</a>
           <a class="language-option" href="/en/workflows" hreflang="en" lang="en">EN</a>

package/evals/private-holdout-v1/public-exposure.v2.json

@@ -256,8 +256,8 @@
     },
     {
       "path": "tests",
-      "fileCount": 510,
-      "sha256": "e82a688b358ea09cee0dd6024c78e4552e0e9516c0c7b24014ae8bdb4b3b7524"
+      "fileCount": 517,
+      "sha256": "8c5cc0362e54e3b4f88047b696232895c479eb2ea93337b19e1e0a436d712ec1"
     }
   ],
   "custodianComparisonRules": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/platform",
-  "version": "1.9.3",
+  "version": "1.10.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public",

package/packages/piagent-core/managed/grant-share.mjs

@@ -0,0 +1,18 @@
+// Every renew replaces the role's token. Searches of one role running side
+// by side, and a delegate refreshing main beside main's search, share one
+// renew, so none voids a sibling's token before Studio admits its request.
+// The share lasts while one of them still runs, at most a minute (the lease
+// is two). `owner` is the ManagedSession.
+export function shareGrant(owner, role) {
+  owner.sharedGrants ??= new Map();
+  const shared = owner.sharedGrants.get(role);
+  if (shared && Date.now() - shared.at < 60_000) { shared.users++; return shared; }
+  const entry = { at: Date.now(), users: 1, grant: owner.broker.request('renew', { role }) };
+  entry.grant.catch(() => { if (owner.sharedGrants.get(role) === entry) owner.sharedGrants.delete(role); });
+  owner.sharedGrants.set(role, entry);
+  return entry;
+}
+
+export function releaseGrant(owner, role, entry) {
+  if (--entry.users <= 0 && owner.sharedGrants?.get(role) === entry) owner.sharedGrants.delete(role);
+}

package/packages/piagent-core/managed/helper-roles.mjs

@@ -1,4 +1,4 @@
-import { REVIEW_PROMPT, VERIFY_PROMPT, isCheckCommand } from './workflow.mjs';
+import { REVIEW_PROMPT, VERIFY_PROMPT, BRIEF_CHECK, BRIEF_ISSUES_JSON, isCheckCommand } from './workflow.mjs';
 
 // Each helper role runs at most this often per user message (Studio's MaxHelperCalls).
 export const HELPER_CALLS = 8;
@@ -25,6 +25,8 @@ export function helperPrompt(roles) {
   if (roles.includes('research')) lines.push(roles.includes('scout') ? 'Use the research helper (delegate role "research") for anything on the web (current information, news, library and API docs, releases, error messages), together with the code when needed; give it the question and the answer you need, and work from its summary.'
     : `Use the research helper (delegate role "research") for anything on the web (current information, news, documentation) and ${WIDE_READING}; work from its findings and do small code lookups yourself.`);
   if (roles.includes('verify')) lines.push('Before you report a non-trivial result as done, you may have the verify helper (delegate role "verify") confirm it independently: it runs the repository checks on the current code and checks claims against the code and primary sources, answering pass, fail or unverifiable with evidence.');
+  // Helpers read the member's request beside the brief and may object to it.
+  if (lines.length) lines.push('A helper sees the member\'s request next to your brief and may object to the brief with evidence (brief_issues). You decide, but answer every objection: send a corrected brief, change your approach, or tell the member why it does not hold. A helper that objects twice for one message goes to the member.');
   return lines.length ? ' ' + lines.join(' ') : '';
 }
 const HELPER_USES = {
@@ -37,8 +39,10 @@ const HELPER_USES = {
 export function delegateDescription(roles) {
   return `Hand work to a helper with its own context. Helpers read the project but cannot change files or call helpers. ${roles.map(role => HELPER_USES[role](roles)).join(' ')} A lookup that one grep or read answers stays with you. Write the task as a brief the helper can act on alone: the goal, what to find or check, where to start and what you already know or ruled out, and the answer you need (file:line facts). One call per helper runs at a time; each can be called again, up to ${HELPER_CALLS} times per user message, for example a second review after fixing what the first one found.`;
 }
-const RESEARCH_PROMPT = 'Research the assigned question. Read only the needed source; use web_search or web_fetch for external documentation. Answer with facts the main agent can act on: file:line, short quotes, what calls what, and what you checked and found nothing in. You cannot change files or delegate.';
-const SCOUT_PROMPT = 'Scout the codebase for the assigned question. Search first (grep, find), then read only the parts that matter. Answer with facts the main agent can act on: file:line, short quotes, what calls what, and where you looked and found nothing. You have no web access: when the answer needs external documentation, say so. You cannot change files or delegate.';
+// Scout and research end with their objections to the brief, if any.
+const OBJECTIONS = `${BRIEF_CHECK} End your answer with one JSON object in a \`\`\`json block: {${BRIEF_ISSUES_JSON}}, with an empty list when the brief is sound. You cannot change files or delegate.`;
+const RESEARCH_PROMPT = `Research the assigned question. Read only the needed source; use web_search or web_fetch for external documentation. Answer with facts the main agent can act on: file:line, short quotes, what calls what, and what you checked and found nothing in. ${OBJECTIONS}`;
+const SCOUT_PROMPT = `Scout the codebase for the assigned question. Search first (grep, find), then read only the parts that matter. Answer with facts the main agent can act on: file:line, short quotes, what calls what, and where you looked and found nothing. You have no web access: when the answer needs external documentation, say so. ${OBJECTIONS}`;
 export const READ_TOOLS = ['read', 'grep', 'find', 'ls'];
 // What each helper may use. Every helper's project is read-only; verify also
 // runs commands there (offline, writes only to its temporary directory).
@@ -56,7 +60,7 @@ export function countedCheck(managed, tool) {
   return { ...tool, execute: async (...args) => {
     const counted = managed.run && isCheckCommand(args[1]?.command, managed.checks.commands), before = counted ? await managed.digest() : null;
     let ok = false;
-    try { const result = await tool.execute(...args); ok = true; return result; }
+    try { const result = await tool.execute(...args); ok = !result?.isError; return result; }
     finally {
       const after = counted && before !== null ? await managed.digest() : null;
       if (after !== null && after === before) await managed.run.afterTool('bash', args[1], ok, async () => after);

package/packages/piagent-core/managed/helper-run.mjs

@@ -0,0 +1,116 @@
+// A helper role's run: its grant from Studio, its read-only sessions (one per
+// part of a large patch for a review), the receipt and the review it records.
+// A helper whose company model account is out of usage, or resting after a
+// refusal, starts once more: Studio then gives the new helper the next model
+// of its role that serves (an auto role's list).
+import { ManagedToolBoundary } from './tool-boundary.mjs';
+import { managedResourceLoader } from './resource-loader.mjs';
+import { shareGrant, releaseGrant } from './grant-share.mjs';
+import { describeFailure, failureCode } from '../runtime/managed-failure.mjs';
+import { reviewParts, mergeReviews, REVIEW_PARALLEL } from './patch-snapshot.mjs';
+import { reviewFindings, briefIssues } from './workflow.mjs';
+import { anchorText, relayObjection, recordVerdicts } from './objections.mjs';
+import { HELPER_CALLS, HELPER_SETUP, READ_TOOLS, countedCheck } from './helper-roles.mjs';
+
+const textContent = result => result.content?.filter(p => p.type === 'text').map(p => p.text).join('\n') ?? '';
+// A helper failure that another model of its role may not have: the model's
+// company account is out of usage or resting, was switched off or removed
+// under the helper, or none serves it now. The new helper is a new
+// conversation for Studio, so it is not held to the old account.
+const HELPER_SWITCH = new Set(['upstream_rate_limited', 'session_account_not_ready_retry_later', 'session_account_unavailable_start_new_session', 'account_capacity_unavailable', 'execution_capability_unavailable']);
+const HELPER_ATTEMPTS = 2;
+
+export async function runHelper(managed, role, task, signal, harness, { verifyGrant, patiently }) {
+  const snapshot = role === 'review' ? await managed.patchSnapshot() : null, parts = snapshot ? reviewParts(snapshot) : null;
+  // A helper whose company model account is out of usage, or resting after
+  // a refusal, starts once more: Studio then gives the new helper the next
+  // model of its role that serves (an auto role's list). Helpers read and
+  // run checks only, so starting over repeats no change.
+  for (let attempt = 1; ; attempt += 1) {
+    try { return await helperAttempt(managed, role, task, signal, harness, snapshot, parts, { verifyGrant, patiently }); }
+    catch (error) {
+      if (attempt >= HELPER_ATTEMPTS || signal?.aborted || !HELPER_SWITCH.has(failureCode(error?.message)) || (managed.helperCalls.get(role) ?? 0) >= HELPER_CALLS) throw error;
+    }
+  }
+}
+async function helperAttempt(managed, role, task, signal, harness, snapshot, parts, { verifyGrant, patiently }) {
+  // A long local tool step may outlive the main lease. Refresh authority
+  // before asking for a child; the broker serializes concurrent renewals,
+  // and main's own searches running beside it share managed renew.
+  let grant;
+  try {
+    const share = shareGrant(managed, 'main');
+    try {
+      const parent = await share.grant;
+      verifyGrant(parent, managed.manifest, 'main'); managed.grant = parent;
+      grant = await patiently(() => managed.broker.request('child', { role }), 2);
+    } finally { releaseGrant(managed, 'main', share); }
+    managed.helperCalls.set(role, (managed.helperCalls.get(role) ?? 0) + 1);
+    try { verifyGrant(grant, managed.manifest, role); }
+    catch (error) { try { await managed.broker.request('close', { role }); } catch { /* closes with the run */ } throw error; }
+  } catch (error) { throw Error(`managed-helper-failed: ${describeFailure(role, error?.message)}`); }
+  let boundary;
+  const sessions = new Set();
+  try {
+    const runtime = await managed.api.ModelRuntime.create({ credentials: new managed.ai.InMemoryCredentialStore(), modelsPath: null, refreshOnCreate: false, allowModelNetwork: false });
+    const model = managed.installModel(runtime, grant); managed.wrapStreams(runtime, role);
+    const setup = HELPER_SETUP[role];
+    boundary = new ManagedToolBoundary({ cwd: managed.cwd, sdkRoot: managed.sdk, protectedRoots: managed.protectedRoots, readOnly: true, commands: setup.commands });
+    const checks = role === 'verify' ? `\n\nRepository checks: ${managed.checks.commands.length ? managed.checks.commands.map(c => '`' + c + '`').join(', ') : 'none declared or detected; choose the tests, type check or build that cover the claims'}.` : '';
+    // One helper session answers the brief (with one part of the patch for a
+    // review in parts); its reply and tokens. A helper runs at its role's
+    // level from Studio (fixed by the Harness, or its main agent's).
+    const ask = async extra => {
+      const { session } = await managed.api.createAgentSession({ cwd: managed.cwd, model, modelRuntime: runtime, thinkingLevel: grant.effort || 'off',
+        settingsManager: managed.api.SettingsManager.inMemory({ retry: { enabled: false, provider: { maxRetries: 0 } }, cacheWarming: 'off' }),
+        sessionManager: managed.api.SessionManager.inMemory(managed.cwd), noTools: 'builtin', tools: [...READ_TOOLS, ...(setup.commands ? ['bash'] : []), ...(setup.web ? ['web_search', 'web_fetch'] : [])],
+        customTools: [...boundary.tools(managed.api).filter(tool => READ_TOOLS.includes(tool.name) || setup.commands && tool.name === 'bash').map(tool => countedCheck(managed, tool)),
+          ...(setup.web ? managed.webTools(runtime, role) : [])], resourceLoader: managedResourceLoader(managed.api, { systemPrompt: setup.prompt }) });
+      sessions.add(session);
+      const abort = () => void session.abort(); signal?.addEventListener('abort', abort, { once: true });
+      try { if (signal?.aborted) throw Error('managed-helper-cancelled'); await session.prompt(anchorText(managed.session.sessionManager, harness) + task + checks + extra, { expandPromptTemplates: false }); }
+      finally { signal?.removeEventListener('abort', abort); }
+      const messages = session.messages.filter(m => m.role === 'assistant');
+      // The main agent (and the member) learn why a helper failed, not just that it did.
+      if (messages.at(-1)?.stopReason === 'error') throw Error(`managed-helper-failed: ${messages.at(-1).errorMessage}`);
+      // Stopped by the member: say so, rather than that the helper failed.
+      if (!messages.length || messages.at(-1).stopReason === 'aborted') throw Error(signal?.aborted ? 'managed-helper-cancelled' : 'managed-helper-failed');
+      return { reply: messages.map(textContent).join('\n'), usage: messages.reduce((n, m) => n + (m.usage?.totalTokens ?? 0), 0) };
+    };
+    let reply, usage, review = null;
+    if (!parts || parts.parts.length === 1) {
+      ({ reply, usage } = await ask(parts ? `\n${parts.parts[0].text}` : ''));
+      reply = reply.slice(0, 16000);
+    } else {
+      // A large patch: one reviewer per part, REVIEW_PARALLEL at a time (Studio
+      // admits one request of a role at a time); the first part that fails
+      // stops the others.
+      const answers = new Array(parts.parts.length);
+      let next = 0;
+      const reviewer = async () => {
+        while (next < parts.parts.length) { const i = next++; answers[i] = await ask(`\n${parts.parts[i].text}`); }
+      };
+      try { await Promise.all(Array.from({ length: Math.min(REVIEW_PARALLEL, parts.parts.length) }, reviewer)); }
+      catch (error) { next = parts.parts.length; for (const session of sessions) void session.abort(); throw error; }
+      review = mergeReviews(parts, answers, { findingsOf: reviewFindings, issuesOf: briefIssues });
+      ({ reply, usage } = review);
+    }
+    const stale = snapshot ? (await managed.patchDigest()) !== snapshot.digest : false;
+    const details = { role, runID: grant.run_id, tokens: usage, patchDigest: snapshot?.digest, stale };
+    if (snapshot) {
+      // Severity-graded findings decide whether the harness sends the agent back.
+      const findings = review ? review.findings : reviewFindings(reply);
+      Object.assign(details, { parsed: review ? review.parsed : !!findings, findings: (findings ?? []).slice(0, 40), blocking: findings?.filter(f => f.severity === 'blocking').length ?? 0 });
+      if (review) Object.assign(details, { parts: parts.parts.length, unread: parts.omitted.map(o => o.path).slice(0, 50) });
+      if (managed.run) { managed.run.reviews += 1; managed.run.blocking += details.blocking; }
+      managed.review = details;
+      managed.session.sessionManager.appendCustomEntry('agent-watch-review', details);
+    }
+    const verdicts = role === 'verify' ? recordVerdicts(managed.run, reply, harness, details) : '';
+    await managed.session.sendCustomMessage({ customType: 'agent-watch-helper-receipt', display: true,
+      content: `${setup.label}: ${usage.toLocaleString('en-US')} tokens${verdicts}${review ? ` · ${parts.parts.length} parts` : ''}${snapshot ? (stale ? ' · review is stale' : ' · patch ' + snapshot.digest.slice(0, 12)) : ''}.`, details }, { triggerTurn: false });
+    // An objection to the brief comes with the answer; a stale review has none to act on.
+    const objection = stale ? '' : await relayObjection(managed, role, reply, harness);
+    return { content: [{ type: 'text', text: stale ? 'Review is stale: the patch changed during review. Obtain a new review for the current patch.' : reply + objection }], details };
+  } finally { for (const session of sessions) session.dispose(); await boundary?.dispose(); await managed.broker.request('close', { role }); }
+}

package/packages/piagent-core/managed/member-questions.d.mts

@@ -0,0 +1,15 @@
+export type MemberQuestion = { header: string; question: string; options: Array<{ label: string; description: string }>; multiSelect: boolean };
+export type MemberAnswer = { skipped: boolean; answers: Array<{ selected: number[]; other: string | null }> };
+export type MemberQuestionEvent = { type: "asked" | "waiting" | "answered" | "withdrawn"; ref: string; reason?: string };
+export function normalizeQuestions(raw: unknown): MemberQuestion[] | null;
+export function normalizeAnswer(questions: MemberQuestion[], raw: unknown): MemberAnswer | null;
+export function answerText(questions: MemberQuestion[], answer: MemberAnswer): string;
+export const memberQuestions: {
+  pulseMs: number;
+  bindSurface(sessionId: string, onEvent: (event: MemberQuestionEvent) => void): () => void;
+  hasSurface(sessionId: string): boolean;
+  ask(input: { sessionId: string; toolCallId: string; questions: MemberQuestion[]; signal?: AbortSignal }): Promise<MemberAnswer>;
+  pending(sessionId: string): Array<{ questionRef: string; askedAt: string; questions: MemberQuestion[] }>;
+  answer(sessionId: string, questionRef: string, raw: unknown): { questionRef: string; state: "answered" };
+};
+export function askTool(managed: unknown): unknown;