@piagent/platform 1.47.0 → 1.48.0

package/packages/piagent-core/managed/command-tools.mjs

@@ -1,49 +1,55 @@
 import { spawn } from 'node:child_process';
-import { asksNothing, broadAccess, networkConfirmation } from './permission.mjs';
+import { asksOnlyHandoff, broadAccess, effectivePermission, networkConfirmation } from './permission.mjs';
+import { handoffReason } from '../runtime/policy/handoff-policy.mjs';
 import { engineAlive, engineLauncher } from './container-engine.mjs';
 import { MEMBER_ONLY, memberOnlyReason, credentialReason, runHostCommand } from './host-command.mjs';
 import { processTools } from './background-process.mjs';
 import { checkpointsOf } from './checkpoints.mjs';
 import { detachedEmulator, simulatorCommandReason } from './simulator-commands.mjs';
 
-// Commands that leave the plain sandbox, each after the member approves that
-// exact command: run_with_network (internet, a local server or browser),
-// run_with_docker when this machine has Docker (the same plus the engine's
-// socket) and run_on_host (on the member's machine, outside the sandbox).
-// Bypass runs the first two without asking (owner, 2026-10-09), except what
-// must be confirmed for any command (bypass-policy.mjs: pushes, deploys,
-// registry logins, deletes known only at run time). run_on_host asks in every
-// mode but Bypass; Bypass still asks when the command reaches credentials.
+// Commands that leave the plain sandbox: run_with_network (internet, a local
+// server or browser), run_with_docker when this machine has Docker (the same
+// plus the engine's socket), run_on_host (on the member's machine, outside the
+// sandbox) and run_on_simulator. What each mode asks (permission.mjs):
+// - Ask first: every command.
+// - Full access: run_with_network, run_with_docker and run_on_simulator run,
+//   except the handoff and destructive steps (mustConfirm); run_on_host asks
+//   every command.
+// - Bypass: all four run, except the handoff (handoffReason: push, PR,
+//   publish, deploy, remote and cloud tools, uploads) and, on the host, a
+//   command that reaches credentials.
 const PARAMETERS = { type: 'object', properties: { command: { type: 'string', minLength: 1, maxLength: 4000 }, reason: { type: 'string', minLength: 1, maxLength: 300 }, timeout: { type: 'number', minimum: 1, maximum: 1800 } }, required: ['command', 'reason'], additionalProperties: false };
 
 const KINDS = {
   network: {
     name: 'run_with_network', label: 'Run with network', scope: 'network-command-once', provider: 'network', riskClass: 'medium',
-    description: 'Run one shell command that needs the internet beyond the package registries bash already reaches (a download site or registry the package proxy refuses), or that starts a local server or a browser (end-to-end tests with Playwright\'s Chromium against a server on 127.0.0.1), after the user approves that exact command. Normal bash has no internet; on macOS it reaches servers on this Mac and runs Playwright\'s Chromium against them, except while a local proxy listens. Credentials (.npmrc, SSH keys, Keychain) stay unavailable, so private registries and git push are not possible here.',
+    description: 'Run one shell command that needs the internet beyond the package registries bash already reaches (a download site or registry the package proxy refuses), or that starts a local server or a browser (end-to-end tests with Playwright\'s Chromium against a server on 127.0.0.1), after the user approves that exact command (Full access and Bypass run it without asking, but a push, publish, deploy or upload is always asked). Normal bash has no internet; on macOS it reaches servers on this Mac and runs Playwright\'s Chromium against them, except while a local proxy listens. Credentials (.npmrc, SSH keys, Keychain) stay unavailable, so private registries and git push are not possible here.',
     allow: 'Run this exact command once, with internet access; a server it starts accepts connections while it runs.',
     title: 'Chạy lệnh có internet', allowText: 'chạy đúng lệnh này một lần, có internet; server nó mở nhận kết nối trong lúc chạy.',
     confirm: (self, command) => networkConfirmation(self, command),
   },
   docker: {
     name: 'run_with_docker', label: 'Run with Docker', scope: 'docker-command-once', provider: 'docker', riskClass: 'high',
-    description: 'Run one shell command that needs the Docker engine of this machine: docker, docker compose (a database or service for tests), docker build, or tests that start containers themselves (Testcontainers), after the user approves that exact command. It has internet access too. Normal bash and run_with_network cannot reach Docker. Mount only folders inside the project. Registry credentials are unavailable: public images pull, private registries and docker push do not. Containers started in the background (-d, compose up -d) keep running after the command: stop them (docker compose down) when the work is done unless the member wants them kept.',
+    description: 'Run one shell command that needs the Docker engine of this machine: docker, docker compose (a database or service for tests), docker build, or tests that start containers themselves (Testcontainers), after the user approves that exact command (Full access and Bypass run it without asking, but docker push or login and any other handoff is always asked). It has internet access too. Normal bash and run_with_network cannot reach Docker. Mount only folders inside the project. Registry credentials are unavailable: public images pull, private registries and docker push do not. Containers started in the background (-d, compose up -d) keep running after the command: stop them (docker compose down) when the work is done unless the member wants them kept.',
     allow: 'Run this exact command once, with internet access and the Docker engine; a container it starts can read folders Docker shares from this machine and may keep running.',
     title: 'Chạy lệnh dùng Docker', allowText: 'chạy đúng lệnh này một lần, có internet và Docker; container nó tạo có thể đọc thư mục Docker được chia sẻ trên máy và có thể tiếp tục chạy.',
     confirm: (self, command) => networkConfirmation(self, command),
   },
   host: {
     name: 'run_on_host', label: 'Run on this machine', scope: 'host-command-once', provider: 'host', riskClass: 'high',
-    description: 'Run one shell command on the member\'s machine, outside the sandbox, as the member, after they approve that exact command. Use it when the sandbox blocks what the task needs and no other tool covers it: install a runtime or tool the project needs (brew install openjdk@21, brew install node@22, sdk install java…), git pull or git push with the member\'s sign-in, a private registry, a file outside the project. It has the member\'s files, Keychain and sign-ins, so ask only for what the task needs and say why in reason. No input can be typed: commands that need the member\'s password (sudo, a .pkg installer) or an interactive sign-in are refused; ask the member with ask_user for those.',
+    description: 'Run one shell command on the member\'s machine, outside the sandbox, as the member, after they approve that exact command (only Bypass runs it without asking, and even there a push, PR, publish, deploy or a command that reaches credentials is asked). Use it when the sandbox blocks what the task needs and no other tool covers it: install a runtime or tool the project needs (brew install openjdk@21, brew install node@22, sdk install java…), git pull with the member\'s sign-in, git push only when the member asked for it, a private registry, a file outside the project. It has the member\'s files, Keychain and sign-ins, so ask only for what the task needs and say why in reason. No input can be typed: commands that need the member\'s password (sudo, a .pkg installer) or an interactive sign-in are refused; ask the member with ask_user for those.',
     allow: 'Run this exact command once on this machine, outside the sandbox, as you: it can read and change your files and use your sign-ins.',
     title: 'Chạy lệnh trên máy (ngoài sandbox)', allowText: 'chạy đúng lệnh này một lần trên máy bạn, ngoài sandbox, bằng quyền của bạn: lệnh đọc/sửa được file và dùng được tài khoản đã đăng nhập trên máy.',
     // Full access does not cover it: the member approves each command (with
-    // what Full access would still have asked about). Bypass asks only about
-    // credentials: a prompt injection's "cat ~/.ssh/id_rsa" is never silent.
-    confirm: async (self, command) => asksNothing(self) ? credentialReason(command) : await networkConfirmation(self, command) ?? 'ask',
+    // what Full access would still have asked about). Bypass asks about the
+    // handoff and about credentials: a prompt injection's "cat ~/.ssh/id_rsa"
+    // or "git push --force" is never silent.
+    confirm: async (self, command) => asksOnlyHandoff(self) ? credentialReason(command) ?? await handoffReason(command) : await networkConfirmation(self, command) ?? 'ask',
   },
   // The sandbox reaches neither CoreSimulator nor adb. Simulator and app build
   // commands only (simulator-commands.mjs), asked about as network commands:
-  // Full access and Bypass run them, except what reaches credentials.
+  // Full access and Bypass run them, except what reaches credentials and what
+  // either mode asks about any command.
   simulator: {
     name: 'run_on_simulator', label: 'Run on simulator', scope: 'simulator-command-once', provider: 'host', riskClass: 'medium',
     description: 'Run one iOS Simulator or Android emulator command on the member\'s machine, outside the sandbox. iOS: xcrun simctl (list, boot, bootstatus -b, install, launch, terminate, openurl, io <device> screenshot <file>, ui appearance, status_bar, spawn <device> log show --info --last 5m --predicate \'process == "<App>"\'), xcodebuild with a simulator destination (build, test: XCUITest is the reliable way to tap, type and answer system dialogs), xcodegen generate, axe (describe-ui reads the screen\'s elements; tap, type, swipe where this Xcode accepts them), open -a Simulator (some Xcode versions run simulators without that window; the device works without it). Android: adb (devices, install, shell am start, shell input tap/text/swipe, exec-out screencap -p > <file>, logcat -d), emulator -avd <name> (started in the background), avdmanager, ./gradlew installDebug. Also flutter, pod install, npx expo/react-native/cap, mkdir -p and cd inside the project. Parts may be joined by && or || and piped into grep, head, tail, xcbeautify or jq; files may be written only inside the project or to /dev/null. Read a screenshot you saved with read to see the screen. Other commands: run_on_host.',
@@ -60,14 +66,34 @@ async function engineReady(boundary) {
 }
 const DOCKER_STOPPED = 'managed-docker-unreachable: Docker engine trên máy không chạy. Gọi start_docker để xin member duyệt mở Docker, rồi chạy lại đúng lệnh này bằng run_with_docker.';
 
-// One approval of the member (the dashboard card, else the Terminal).
+// Why a mode that runs commands without asking asks about this one, as the
+// card says it: the mode named as it is.
+export function stillAsks(self, reason) {
+  return effectivePermission(self) === 'bypass' ? { en: `Bypass still asks: ${reason}`, vi: `Bypass vẫn hỏi: ${reason}` }
+    : { en: `Full access still asks: ${reason}`, vi: `Full access vẫn hỏi: ${reason}` };
+}
+
+// One approval of the member (the dashboard card, else the Terminal). The
+// member may allow it once, allow the same exact action for the rest of the
+// conversation (never a handoff: its scope names it), deny it, or deny it and
+// stop the turn so the agent does not try again.
+const CHOICES = { once: 'Đồng ý một lần', session: 'Đồng ý cho cả cuộc trò chuyện (đúng lệnh này)', deny: 'Từ chối', stop: 'Từ chối và dừng lượt này' };
 export async function approve(self, id, signal, ctx, action, { title, body }) {
+  const grantable = !/handoff/.test(String(action.requestedScope ?? '')), key = `${action.toolName}\u0000${action.commandPreview ?? JSON.stringify(action.rawAction ?? {})}`;
+  if (grantable && self.sessionApprovals?.has(key)) return;
   const { piApprovalBroker } = await import('../runtime/inspection/approval-broker.ts');
+  const choices = ['once', ...(grantable ? ['session'] : []), 'deny', 'stop'];
   const decision = await piApprovalBroker.request({ cwd: self.cwd, rawSessionId: self.session.sessionManager.getSessionId(), toolCallId: id,
     action: { kind: 'external-provider-action', preconditionClass: 'runtime-only', targetPaths: [self.cwd], urlOrigin: null, ...action },
     terminalConfirm: () => ctx?.ui?.confirm?.(title, body) ?? Promise.resolve(false),
+    ...(ctx?.mode === 'tui' && ctx?.hasUI && typeof ctx.ui?.select === 'function' ? { terminalChoose: async () => {
+      const picked = await ctx.ui.select(`${title}\n\n${body}`, choices.map(choice => CHOICES[choice]));
+      return choices.find(choice => CHOICES[choice] === picked) ?? 'deny';
+    } } : {}),
     unavailableFallback: 'terminal-confirm', recheck: () => !signal?.aborted && Boolean(self.grant) });
+  if (!decision.allowed && decision.choice === 'stop') { try { ctx?.abort?.(); } catch { /* the denial below still stands */ } throw Error('managed-operation-denied-stop: bạn đã từ chối và dừng lượt này; không thử lại, chờ member.'); }
   if (!decision.allowed || !decision.consume() || signal?.aborted) throw Error('managed-operation-denied');
+  if (decision.choice === 'session' && grantable) (self.sessionApprovals ??= new Set()).add(key);
 }
 
 function commandTool(self, kind) {
@@ -80,10 +106,13 @@ function commandTool(self, kind) {
       const notSimulator = kind === 'simulator' ? simulatorCommandReason(args.command, self.cwd) : null;
       if (notSimulator) throw Error(`managed-simulator-command: ${notSimulator}.`);
       const confirm = await spec.confirm(self, args.command);
-      if (confirm !== null) await approve(self, id, signal, ctx, { toolName: spec.name, rawAction: { command: args.command }, commandPreview: String(args.command),
-        provider: spec.provider, requestedScope: spec.scope, reason: (confirm === 'ask' ? String(args.reason) : `Full access still asks: ${confirm}. ${args.reason}`).slice(0, 300), riskClass: spec.riskClass,
-        allowConsequence: spec.allow, denyConsequence: 'The command does not run; the agent is told you declined.' },
-      { title: spec.title, body: `${args.command}\n\nLý do: ${args.reason}${confirm === 'ask' ? '' : `\nBypass vẫn hỏi: ${confirm}`}\n\nĐồng ý: ${spec.allowText}\nTừ chối: lệnh không chạy, agent được báo bạn đã từ chối.` });
+      if (confirm !== null) {
+        const why = confirm === 'ask' ? null : stillAsks(self, confirm), handoff = await handoffReason(args.command);
+        await approve(self, id, signal, ctx, { toolName: spec.name, rawAction: { command: args.command }, commandPreview: String(args.command),
+          provider: spec.provider, requestedScope: handoff ? 'handoff-once' : spec.scope, reason: (why ? `${why.en}. ${args.reason}` : String(args.reason)).slice(0, 300), riskClass: spec.riskClass,
+          allowConsequence: spec.allow, denyConsequence: 'The command does not run; the agent is told you declined.' },
+        { title: spec.title, body: `${args.command}\n\nLý do: ${args.reason}${why ? `\n${why.vi}` : ''}\n\nĐồng ý: ${spec.allowText}\nTừ chối: lệnh không chạy, agent được báo bạn đã từ chối.` });
+      }
       let ok = false;
       if (self.run) await checkpointsOf(self).take();
       const before = await self.changedFiles();
@@ -101,7 +130,8 @@ function commandTool(self, kind) {
 }
 
 // start_docker: the engine the member installed, started after they approve
-// (Bypass starts it without asking: local and reversible), then waited for.
+// (Full access and Bypass start it without asking: local and reversible),
+// then waited for.
 const textResult = text => ({ content: [{ type: 'text', text }], details: {} });
 function startDockerTool(self, { wait = 180_000, every = 2000, launcher: found = engineLauncher, spawnImpl = spawn } = {}) {
   return { name: 'start_docker', label: 'Start Docker',
@@ -134,10 +164,10 @@ export function commandTools(self, options) {
 
 // What the system prompt says about services and what the sandbox blocks: it
 // is read for every request, so a Docker started since shows up.
-const HOST_PROMPT = ' When the sandbox blocks something the task needs (a missing runtime such as a JDK or a Node version, the member\'s sign-in for git pull or git push or a private registry, a file outside the project), do not stop and do not tell the member to run it: request run_on_host with the exact command; it runs on the member\'s machine once they approve. Only what needs the member themselves (their password for sudo or an installer, an interactive sign-in, a window to click) goes to ask_user, with the exact steps and the options to continue or skip; after their answer, check and carry on.';
+const HOST_PROMPT = ' When the sandbox blocks something the task needs (a missing runtime such as a JDK or a Node version, the member\'s sign-in for git pull or a private registry, a file outside the project), do not stop and do not tell the member to run it: request run_on_host with the exact command; it runs on the member\'s machine once they approve. The work ends at the handoff: commit locally, then report what is ready; push, open or merge a pull request, publish or deploy only when the member asked for it in this conversation, and each of those steps is asked about in every access mode. Only what needs the member themselves (their password for sudo or an installer, an interactive sign-in, a window to click) goes to ask_user, with the exact steps and the options to continue or skip; after their answer, check and carry on.';
 export function servicesPrompt(boundary) {
   const simulator = ' The iOS Simulator and Android emulator are not reachable from bash: boot them, build and install the app, launch it, tap and type, and take screenshots with run_on_simulator (save the screenshot in the project, then read it to see the screen). Do not ask the member to run simulator steps you can run.';
-  if (boundary.engine) return ' Docker is available through run_with_docker (the member approves each command): a database or service for tests (docker compose up -d, then the tests through bash or run_with_network), docker build, or Testcontainers tests. If the engine stops answering, start_docker asks the member to start it. Stop what you started when done unless the member wants it kept.' + simulator + HOST_PROMPT;
+  if (boundary.engine) return ' Docker is available through run_with_docker (in Ask first the member approves each command): a database or service for tests (docker compose up -d, then the tests through bash or run_with_network), docker build, or Testcontainers tests. If the engine stops answering, start_docker asks the member to start it. Stop what you started when done unless the member wants it kept.' + simulator + HOST_PROMPT;
   if (boundary.dockerCli) return ' Docker is installed but not running: when the task needs it, call start_docker (the member approves), then run_with_docker.' + simulator + HOST_PROMPT;
   return ' Docker is not installed on this machine: when the task needs it, ask the member with ask_user (install it, or check another way).' + simulator + HOST_PROMPT;
 }

package/packages/piagent-core/managed/fetch-guard.mjs

@@ -1,4 +1,4 @@
-import { asksNothing } from './permission.mjs';
+import { asksOnlyHandoff } from './permission.mjs';
 import { approve } from './command-tools.mjs';
 
 // web_fetch is a request to any public https address: a page that tells the
@@ -6,7 +6,7 @@ import { approve } from './command-tools.mjs';
 // Documentation and package registries are read freely. Another host is asked
 // about once per conversation; an address there that carries a query or a
 // fragment (where data rides along) is asked about every time. Bypass asks
-// only about the latter. A helper cannot ask the member: it is told to hand
+// only about the latter: data sent out is a handoff. A helper cannot ask the member: it is told to hand
 // the address to the main agent.
 const TRUSTED = ['github.com', 'raw.githubusercontent.com', 'docs.github.com', 'npmjs.com', 'www.npmjs.com', 'registry.npmjs.org', 'pypi.org', 'docs.python.org',
   'developer.mozilla.org', 'nodejs.org', 'go.dev', 'pkg.go.dev', 'crates.io', 'docs.rs', 'doc.rust-lang.org', 'learn.microsoft.com', 'developer.apple.com',
@@ -21,7 +21,7 @@ export function fetchDecision(owner, role, raw) {
   if (trustedHost(host)) return null;
   const carries = Boolean(url.search || url.hash), known = owner.fetchHosts?.has(host);
   if (role !== 'main') return carries || !known ? 'refuse' : null;
-  if (asksNothing(owner)) return carries ? 'ask' : null;
+  if (asksOnlyHandoff(owner)) return carries ? 'ask' : null;
   return carries || !known ? 'ask' : null;
 }
 export async function guardFetch(owner, role, raw, id, signal, ctx) {

package/packages/piagent-core/managed/host-command.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import { spawn } from 'node:child_process';
 import { redactedText } from '../runtime/managed-failure.mjs';
+import { commandSegments, stripWrapper } from '../runtime/policy/handoff-policy.mjs';
 
 // Commands the member approved to run on their machine, outside the sandbox
 // (run_on_host, start_docker): installing a runtime the project needs, git
@@ -13,12 +14,14 @@ import { redactedText } from '../runtime/managed-failure.mjs';
 const PASSWORD = new Set(['sudo', 'doas', 'su', 'pkexec', 'passwd']);
 const SIGN_IN = [/^gh auth (login|refresh)\b/, /^(npm|pnpm) (login|adduser)\b/, /^yarn npm login\b/, /^docker login\b(?!.*--password-stdin)/, /^az login\b/,
   /^gcloud auth (login|application-default login)\b/, /^aws (configure\s*$|sso login\b)/, /^(firebase|vercel|wrangler|heroku|netlify) login\b/];
-const WRAPPERS = new Set(['env', 'command', 'exec', 'time', 'nohup']);
+// Read through the shared shell parser (policy-core.js): `(sudo ls)`,
+// `echo x & sudo ls` and `if …; then sudo …` are each a sudo.
 export function memberOnlyReason(command) {
-  for (const part of String(command).split(/&&|\|\||;|\||\n/)) {
-    const words = part.trim().split(/\s+/).filter(Boolean);
-    while (words.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0]) || WRAPPERS.has(words[0]))) words.shift();
-    const name = words[0]?.split('/').pop(), rest = words.join(' ');
+  for (const { words } of commandSegments(command)) {
+    const run = stripWrapper(words), prefix = words.slice(0, words.length - run.length).map(word => word.split('/').pop());
+    const elevated = prefix.find(word => PASSWORD.has(word));
+    if (elevated) return `${elevated} needs the member's password`;
+    const name = run[0], rest = run.join(' ');
     if (PASSWORD.has(name)) return `${name} needs the member's password`;
     if (name === 'installer' || name === 'softwareupdate') return `${name} needs the member's password`;
     if (SIGN_IN.some(rule => rule.test(rest))) return 'an interactive sign-in needs the member';
@@ -26,8 +29,13 @@ export function memberOnlyReason(command) {
   return null;
 }
 // Where credentials live on the member's machine. A command that names one
-// reads or moves secrets, so it is asked about even in Bypass.
-const CREDENTIALS = [/~\/\.(ssh|aws|gnupg|kube|docker|pi|codex|claude|piagent|config\/gh|config\/gcloud|azure|npmrc|netrc|pypirc|git-credentials)\b/, /\$HOME\/\.(ssh|aws|gnupg|kube|docker|pi|codex|claude|piagent)\b/,
+// reads or moves secrets, so it is asked about even in Bypass. A text check,
+// not a boundary: it catches the usual spellings (~/.ssh, $HOME/.ssh,
+// /Users/me/.ssh, `tar -C ~ .ssh`); the sandbox is what keeps secrets out of
+// plain bash. Folders whose names projects also use (.docker, .pi) count only
+// under a home directory.
+const HOME = String.raw`(?:~|\$HOME|\$\{HOME\}|/Users/[^/\s'"]+|/home/[^/\s'"]+|/root)/`;
+const CREDENTIALS = [/(^|[\s'"=:/])\.(ssh|aws|gnupg|kube|azure|npmrc|netrc|pypirc|git-credentials)(\b|\/|$)/, new RegExp(String.raw`${HOME}\.(docker|pi|codex|claude|piagent|config/gh|config/gcloud)\b`),
   /(^|[\s'"/])\.env(\.[\w-]+)?\b/, /\bauth\.json\b/, /\bcredentials(\.json)?\b/, /\bid_(rsa|ed25519|ecdsa|dsa)\b/, /\.(pem|p12|pfx|key)\b/,
   /\bsecurity\s+(find-(generic|internet)-password|dump-keychain|export)\b/, /Library\/Keychains\b/, /\bprintenv\b|(^|[;&|]\s*)env\s*($|[|;&>])/];
 export function credentialReason(command) {

package/packages/piagent-core/managed/member-mcp.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { evaluateMcpApproval } from '../runtime/mcp-repository-gate.mjs';
+import { mcpWriteAction } from '../runtime/policy/handoff-policy.mjs';
 import { userToolchains } from './toolchain.mjs';
 import { fenced } from './untrusted.mjs';
 
@@ -11,9 +12,12 @@ import { fenced } from './untrusted.mjs';
 // configuration as personal Piagent (piagent-mcp add, ~/.config/mcp/mcp.json,
 // a project's .mcp.json, /mcp) and the same logins (/mcp-auth), so a server the
 // member added once works in both. The member decides which servers exist;
-// company sessions keep the two protections personal Piagent has: a server a
-// repository defines runs only once someone on this machine approved it, and
-// what a server returns reaches the agent as data, not instructions.
+// company sessions keep the protections personal Piagent has: a server a
+// repository defines runs only once someone on this machine approved it, a
+// tool that writes to the server's system (create, update, push, merge,
+// publish, send… in its name) is asked about in every access mode, Bypass
+// included, since it hands work to the outside, and what a server returns
+// reaches the agent as data, not instructions.
 
 const ADAPTER = 'pi-mcp-adapter';
 const readJson = file => { try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; } };
@@ -43,14 +47,35 @@ export function memberMcpEnvironment(adapter, home = os.homedir(), env = process
   return env;
 }
 
+// The MCP tool a call runs: the proxy's `tool` (`mcp` with tool and server),
+// or a direct tool the adapter registered. null for anything else.
+export function mcpToolCalled(toolName, input, fromAdapter) {
+  if (toolName === 'mcp') return typeof input?.tool === 'string' && input.tool.trim() ? { tool: input.tool.trim(), server: String(input.server ?? '').trim() } : null;
+  return fromAdapter(toolName) ? { tool: toolName, server: '' } : null;
+}
+
 // The repository approval gate on every tool call (as personal Piagent's
-// guard), and the adapter's results fenced as data.
-export function memberMcpGuard(cwd, adapterDir) {
+// guard), the member's approval of an MCP write, and the adapter's results
+// fenced as data. Without an owner (no conversation to ask in) a write is refused.
+export function memberMcpGuard(cwd, adapterDir, owner = null) {
   return pi => {
     const fromAdapter = name => { const source = pi.getAllTools().find(tool => tool.name === name)?.sourceInfo?.path; return !!source && (source === adapterDir || inside(source, adapterDir)); };
-    pi.on('tool_call', event => {
+    pi.on('tool_call', async (event, ctx) => {
       const decision = evaluateMcpApproval(cwd, event.toolName, event.input ?? {});
-      return decision.block ? { block: true, reason: decision.reason } : undefined;
+      if (decision.block) return { block: true, reason: decision.reason };
+      const called = mcpToolCalled(event.toolName, event.input, fromAdapter);
+      const action = called && await mcpWriteAction(called.tool);
+      if (!action) return undefined;
+      if (!owner) return { block: true, reason: `MCP tool ${called.tool} writes outside (${action}) and no member can approve it here.` };
+      const { approve } = await import('./command-tools.mjs');
+      const name = called.server ? `${called.server} → ${called.tool}` : called.tool, args = JSON.stringify(event.input?.args ?? event.input ?? {}).slice(0, 600);
+      try {
+        await approve(owner, event.toolCallId, ctx?.signal, ctx, { toolName: event.toolName, rawAction: { tool: called.tool, server: called.server, input: event.input ?? {} }, commandPreview: name,
+          provider: called.server || 'mcp', requestedScope: 'mcp-handoff-once', reason: `The MCP tool ${name} writes outside this machine (${action}); every access mode asks before a handoff.`, riskClass: 'high',
+          allowConsequence: 'Run this exact MCP call once; it changes the system behind that server.', denyConsequence: 'The call does not run; the agent is told you declined.' },
+        { title: 'Công cụ MCP ghi ra ngoài', body: `${name}\n${args}\n\nCông cụ này ${action} trên hệ thống của server MCP. Mọi chế độ truy cập, kể cả Bypass, đều hỏi trước việc bàn giao ra ngoài.\n\nĐồng ý: chạy đúng lệnh gọi này một lần.\nTừ chối: không chạy, agent được báo bạn đã từ chối.` });
+      } catch { return { block: true, reason: `User denied MCP tool ${name}.` }; }
+      return undefined;
     });
     pi.on('tool_result', event => {
       if (!fromAdapter(event.toolName)) return undefined;
@@ -63,9 +88,9 @@ export function memberMcpGuard(cwd, adapterDir) {
 
 // The company session's own extension factories, with the member's MCP added
 // when the adapter is installed: [factories, extension paths] for inlineExtensions.
-export function withMemberMcp(cwd, factories, home = os.homedir()) {
+export function withMemberMcp(cwd, factories, home = os.homedir(), owner = null) {
   const adapter = memberMcpAdapter(home);
   if (!adapter) return [factories, []];
   memberMcpEnvironment(adapter, home);
-  return [[...factories, memberMcpGuard(cwd, adapter.dir)], [adapter.dir]];
+  return [[...factories, memberMcpGuard(cwd, adapter.dir, owner)], [adapter.dir]];
 }

package/packages/piagent-core/managed/permission.mjs

@@ -1,11 +1,13 @@
 // A company conversation's access, chosen by the member and kept with the
-// conversation: "workspace-write" asks before every command that needs the
-// internet; "trusted-full-access" (Full access) asks only for what must be
-// confirmed (runtime/policy/bypass-policy.mjs); "bypass" asks nothing, as
-// Codex's bypass mode, where the team's Harness allows it
+// conversation (runtime/policy/handoff-policy.mjs has both lists):
+// "workspace-write" (Ask first) asks before every command that leaves the
+// sandbox; "trusted-full-access" (Full access) asks only about the handoff and
+// what is destructive (mustConfirm); "bypass" runs the work and asks only about
+// the handoff (handoffReason: push, PR, publish, deploy, remote and cloud
+// tools, uploads), where the team's Harness allows it
 // (harness.configuration.bypass_mode, an administrator's switch in Studio).
-// The sandbox itself stays: bypass removes the questions, not the boundary.
-import { mustConfirm } from '../runtime/policy/bypass-policy.mjs';
+// The sandbox itself stays: bypass removes questions, not the boundary.
+import { handoffReason, mustConfirm } from '../runtime/policy/handoff-policy.mjs';
 
 export const PERMISSIONS = ['workspace-write', 'trusted-full-access', 'bypass'];
 const ENTRY = 'agent-watch-permission';
@@ -36,10 +38,15 @@ export function recordBypass(owner, manager) {
   const last = manager.getEntries().filter(e => e.type === 'custom' && e.customType === ALLOWANCE).at(-1)?.data;
   if ((last?.allowed === true) !== allowed) manager.appendCustomEntry(ALLOWANCE, { allowed, at: new Date().toISOString() });
 }
-// Whether this conversation may skip the questions Full access still asks.
-export const asksNothing = owner => effectivePermission(owner) === 'bypass';
+// Whether this conversation skips the questions Full access still asks
+// (everything but the handoff).
+export const asksOnlyHandoff = owner => effectivePermission(owner) === 'bypass';
 export const broadAccess = owner => ['trusted-full-access', 'bypass'].includes(effectivePermission(owner));
-// Why a network command must still be asked about: null runs it in Full
-// access or Bypass, 'ask' when the member asks first.
-export const networkConfirmation = async (owner, command) => asksNothing(owner) ? null
-  : effectivePermission(owner) === 'trusted-full-access' ? mustConfirm(command) : 'ask';
+// Why a command that leaves the sandbox must be asked about: the reason, or
+// 'ask' in Ask first, or null to run it. Every mode asks about the handoff.
+export const networkConfirmation = async (owner, command) => {
+  const mode = effectivePermission(owner);
+  if (mode === 'bypass') return handoffReason(command);
+  if (mode === 'trusted-full-access') return mustConfirm(command);
+  return 'ask';
+};

package/packages/piagent-core/managed/repository-operation.mjs

@@ -107,7 +107,7 @@ export async function executeRepositoryFetch(boundary,plan,signal,{transport=fet
 }
 
 // The fetch_origin tool of a company conversation: one approved fetch of the
-// GitHub origin (Bypass fetches without asking).
+// GitHub origin (Full access and Bypass fetch without asking: it only downloads).
 export function fetchOriginTool(self) {
   return {name:'fetch_origin',label:'Fetch origin',description:'Request one approved GitHub origin fetch. Refreshes origin branches without changing working files. Does not expose credentials or allow arbitrary network commands. When the conversation folder holds several repositories, pass path: the repository folder inside it. Use this instead of git fetch, which has no GitHub sign-in here.',
     parameters:{type:'object',properties:{path:{type:'string',maxLength:500,description:'Repository folder inside the conversation folder, such as "api"; omit when the conversation folder is the repository.'}},additionalProperties:false},

package/packages/piagent-core/managed/session.mjs

@@ -138,7 +138,7 @@ export class ManagedSession {
     // The Harness workflow (possibly changed on a later enrollment) adds its process to the prompt.
     const loader = managedResourceLoader(api, { systemPrompt: () => BASE_PROMPT + referencePrompt(self.boundary.userHome) + TEST_PROMPT + servicesPrompt(self.boundary) + webPrompt(helperRoles(manifest), mainWebLookups(manifest)) + helperPrompt(helperRoles(self.manifest)) + workflowPrompt(workflowPolicy(self.manifest), self.checks), agentsFiles,
       skills: self.resources.skills, prompts: self.resources.prompts, themes: terminalExtensions.length ? await loadPiagentThemes(sdk) : [], ...await inlineExtensions(api, sdk, self.cwd, // and the member's MCP servers (member-mcp.mjs)
-        ...withMemberMcp(self.cwd, [...terminalExtensions, workflowContextExtension(self.cwd, () => self.session.sessionManager)])) });
+        ...withMemberMcp(self.cwd, [...terminalExtensions, workflowContextExtension(self.cwd, () => self.session.sessionManager)], undefined, self)) });
     const settings = api.SettingsManager.inMemory({ retry: { enabled: false, provider: { maxRetries: 0 } }, cacheWarming: 'off', enableInstallTelemetry: false, enableAnalytics: false, enableSkillCommands: true });
     const manager = sessionManager ?? api.SessionManager.inMemory(self.cwd); attachMemory(self, manager, agentDir, g => verifyGrant(g, self.manifest, 'main')); self.studioLink = new StudioLink({ origin: self.origin, agentDir, notify: event => self.notify(event), ui: () => self.session?.extensionRunner?.getUIContext?.() });
     const scope = scopeOf(self.origin, manifest);
@@ -169,7 +169,7 @@ export class ManagedSession {
     self.session = result.session;
     self.session.managedExecution = true;
     self.turnRetry = enableCompanyTurnRetry(self.session, settings, self.studioLink);
-    // The member's access for this conversation: ask first, or Bypass (permission.mjs).
+    // The member's access for this conversation: Ask first, Full access or Bypass (permission.mjs).
     self.permission = restorePermission(manager); recordBypass(self, manager); self.session.managedSetPermission = permissionSetter(self, manager);
     // Fast mode, where the Harness allows it (fast-mode.mjs): off until the member turns it on.
     self.fast = restoreFast(manager); recordFast(self, manager); self.session.managedSetFast = fastSetter(self, manager); self.session.managedFastState = () => fastState(self); // null where the Harness does not allow it

package/packages/piagent-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/core",
-  "version": "1.47.0",
+  "version": "1.48.0",
   "type": "module",
   "private": true,
   "license": "MIT",

package/packages/piagent-core/runtime/hooks/session-start-hook.ts

@@ -320,7 +320,7 @@ export function registerSessionStartHook(pi: ExtensionAPI, dependencies: Session
       ctx.ui.notify("Piagent permission profile trusted-full-access is active; protected paths, secret redaction, and destructive/external confirmations remain enforced.", "warning");
     }
     if (permissionProfile.mode === "bypass") {
-      ctx.ui.notify("Piagent bypass is active: no confirmation, protected-path or policy gate applies in this personal session. Output redaction and /undo checkpoints remain.", "warning");
+      ctx.ui.notify("Piagent bypass is active: the work runs without confirmation, protected-path or policy gates in this personal session. The handoff (push, PR, publish, deploy, remote tools, MCP writes) is still asked; output redaction and /undo checkpoints remain.", "warning");
     }
     const mcpNotice = dependencies.mcpReadinessNotice(ctx.cwd);
     if (mcpNotice) ctx.ui.notify(mcpNotice, "warning");

package/packages/piagent-core/runtime/inspection/approval-broker.ts

@@ -40,8 +40,15 @@ type Binding = { cwd: string; rawSessionId: string; runtimeInstanceId: string; s
 type Pending = { request: Request; resolve(value: ApprovalGuardDecision): void; receipt: Receipt | null; timer: NodeJS.Timeout;
   finalWaiters: Array<(receipt: Receipt) => void>; recheck(): boolean };
 export type ApprovalBrokerEvent = { kind: "requested" | "resolved" | "expired" | "cancelled"; approvalRef: string; request?: Request; receipt?: Receipt };
-export type ApprovalGuardDecision = { allowed: boolean; brokered: boolean; receipt: Receipt | null;
+// What the member chose: allow this exact action once, allow the same exact
+// action for the rest of the session (offered only where the request allows
+// it, never for a handoff), deny it, or deny it and stop the turn so the
+// agent does not try again. A decision without a choice is once or deny.
+export type ApprovalChoice = "once" | "session" | "deny" | "stop";
+export type ApprovalGuardDecision = { allowed: boolean; brokered: boolean; receipt: Receipt | null; choice: ApprovalChoice;
   consume(): boolean; cancel(reasonCode?: string): void };
+const choiceOf = (allowed: boolean, value?: { scope?: unknown; stop?: unknown }): ApprovalChoice =>
+  allowed ? (value?.scope === "session" ? "session" : "once") : (value?.stop === true ? "stop" : "deny");
 export type ApprovalUnavailableFallback = "terminal-confirm" | "deny";
 
 function canonical(value: unknown): string {
@@ -54,6 +61,12 @@ function exactTimestamp(value: unknown): value is string {
   if (typeof value !== "string" || !TIMESTAMP.test(value)) return false;
   const parsed = Date.parse(value); return Number.isFinite(parsed) && new Date(parsed).toISOString() === value;
 }
+// The member's answer in the terminal: their choice where the caller offers
+// the four, else yes or no.
+function terminalChoice(input: { terminalConfirm(): Promise<boolean>; terminalChoose?(): Promise<ApprovalChoice> }): () => Promise<ApprovalChoice> {
+  return input.terminalChoose ? () => input.terminalChoose!() : () => input.terminalConfirm().then((allow) => allow ? "once" as const : "deny" as const);
+}
+
 function exactKeys(value: unknown, keys: string[]): boolean {
   return Boolean(value && typeof value === "object" && !Array.isArray(value)
     && canonical(Object.keys(value as Record<string, unknown>).sort()) === canonical([...keys].sort()));
@@ -135,7 +148,7 @@ export class PiApprovalBroker {
   }
 
   async request(input: { cwd: string; rawSessionId: string; toolCallId: string; action: ApprovalActionDraft;
-    expectedTask?: { taskId: string; taskRunId: string } | null; terminalConfirm(): Promise<boolean>;
+    expectedTask?: { taskId: string; taskRunId: string } | null; terminalConfirm(): Promise<boolean>; terminalChoose?(): Promise<ApprovalChoice>;
     unavailableFallback?: ApprovalUnavailableFallback; recheck?(): boolean; ttlMs?: number }): Promise<ApprovalGuardDecision> {
     const binding = this.#bindings.get(key(input.cwd, input.rawSessionId));
     const authority = binding?.authority();
@@ -166,8 +179,8 @@ export class PiApprovalBroker {
       while (binding.requests.size > MAX_PENDING + MAX_RECENT) binding.requests.delete(binding.requests.keys().next().value as string);
     });
     this.#emit(binding, { kind: "requested", approvalRef, request: clone(request) });
-    void Promise.resolve().then(input.terminalConfirm).then(
-      (allow) => this.#settle(binding, approvalRef, allow ? "allow" : "deny", "terminal", ref("decision", binding.secret, [approvalRef, "terminal", now])),
+    void Promise.resolve().then(terminalChoice(input)).then(
+      (choice) => this.#settle(binding, approvalRef, choice === "once" || choice === "session" ? "allow" : "deny", "terminal", ref("decision", binding.secret, [approvalRef, "terminal", now]), choice),
       () => this.#settle(binding, approvalRef, "deny", "terminal", ref("decision", binding.secret, [approvalRef, "terminal-error", now]))
     );
     return result;
@@ -191,20 +204,21 @@ export class PiApprovalBroker {
     }
     if (Date.now() >= Date.parse(pending.request.expiresAt)) { this.#expire(binding, approvalRef); throw new Error("approval-expired"); }
     const final = new Promise<Receipt>((resolve) => pending.finalWaiters.push(resolve));
-    this.#settle(binding, approvalRef, decision.decision, "webui", decision.decisionId);
+    this.#settle(binding, approvalRef, decision.decision, "webui", decision.decisionId, choiceOf(decision.decision === "allow", decision));
     if (decision.decision === "deny") return clone(binding.recent.at(-1)!);
     return final;
   }
 
-  #terminalOnly(confirm: () => Promise<boolean>): Promise<ApprovalGuardDecision> {
-    return Promise.resolve().then(confirm).then((allowed) => ({ allowed, brokered: false, receipt: null,
-      consume: () => allowed, cancel: () => undefined }), () => ({ allowed: false, brokered: false, receipt: null,
-      consume: () => false, cancel: () => undefined }));
+  #terminalOnly(choose: () => Promise<ApprovalChoice>): Promise<ApprovalGuardDecision> {
+    return Promise.resolve().then(choose).then((choice) => {
+      const allowed = choice === "once" || choice === "session";
+      return { allowed, brokered: false, receipt: null, choice, consume: () => allowed, cancel: () => undefined };
+    }, () => ({ allowed: false, brokered: false, receipt: null, choice: "deny" as const, consume: () => false, cancel: () => undefined }));
   }
 
-  #unavailable(input: { terminalConfirm(): Promise<boolean>; unavailableFallback?: ApprovalUnavailableFallback }): Promise<ApprovalGuardDecision> {
-    if (input.unavailableFallback !== "deny") return this.#terminalOnly(input.terminalConfirm);
-    return Promise.resolve({ allowed: false, brokered: false, receipt: null, consume: () => false, cancel: () => undefined });
+  #unavailable(input: { terminalConfirm(): Promise<boolean>; terminalChoose?(): Promise<ApprovalChoice>; unavailableFallback?: ApprovalUnavailableFallback }): Promise<ApprovalGuardDecision> {
+    if (input.unavailableFallback !== "deny") return this.#terminalOnly(terminalChoice(input));
+    return Promise.resolve({ allowed: false, brokered: false, receipt: null, choice: "deny", consume: () => false, cancel: () => undefined });
   }
 
   #action(binding: Binding, draft: ApprovalActionDraft, cwd: string): Record<string, unknown> {
@@ -238,9 +252,12 @@ export class PiApprovalBroker {
   }
 
   #validDecision(value: unknown, request?: Request, receipt?: Receipt | null): boolean {
+    const optional = value && typeof value === "object" ? ["scope", "stop"].filter((name) => Object.hasOwn(value, name)) : [];
     if (!exactKeys(value, ["schemaVersion", "version", "recordType", "approvalRef", "decisionId", "decisionToken", "identity", "actionDigest",
-      "expectedRevisions", "decision", "reason", "decidedAt", "expiresAt", "decisionSurface", "executor", "directExecution"])) return false;
+      "expectedRevisions", "decision", "reason", "decidedAt", "expiresAt", "decisionSurface", "executor", "directExecution", ...optional])) return false;
     const item = value as any;
+    if (Object.hasOwn(item, "scope") && !(["once", "session"].includes(item.scope) && (item.scope === "once" || item.decision === "allow"))) return false;
+    if (Object.hasOwn(item, "stop") && !(typeof item.stop === "boolean" && (!item.stop || item.decision === "deny"))) return false;
     if (item.schemaVersion !== 1 || item.version !== "piagent-webui-approval-v1" || item.recordType !== "decision"
       || !REF.test(item.approvalRef) || !REF.test(item.decisionId) || typeof item.decisionToken !== "string" || item.decisionToken.length < 32
       || !["allow", "deny"].includes(item.decision) || !exactTimestamp(item.decidedAt) || !exactTimestamp(item.expiresAt)
@@ -258,7 +275,7 @@ export class PiApprovalBroker {
     return value === null || Boolean(REVISION.test(value.workspaceRevision) && (value.indexRevision === null || REVISION.test(value.indexRevision)) && DIGEST.test(value.preimageDigest));
   }
 
-  #settle(binding: Binding, approvalRef: string, decision: "allow" | "deny", surface: "webui" | "terminal", decisionId: string): void {
+  #settle(binding: Binding, approvalRef: string, decision: "allow" | "deny", surface: "webui" | "terminal", decisionId: string, choice: ApprovalChoice = decision === "allow" ? "once" : "deny"): void {
     const pending = binding.pending.get(approvalRef); if (!pending || pending.receipt) return;
     clearTimeout(pending.timer); const resolvedAt = new Date().toISOString();
     const postRevision = this.#nextRevision(binding, "resolved", [approvalRef, decision, surface]);
@@ -272,7 +289,7 @@ export class PiApprovalBroker {
       auditRef: ref("approval-audit", binding.secret, [approvalRef, resolvedAt, surface, decision]), executor: "pi-guard", directExecution: false };
     pending.receipt = receipt; binding.recent.push(receipt); binding.recent = binding.recent.slice(-MAX_RECENT);
     this.#emit(binding, { kind: "resolved", approvalRef, receipt: clone(receipt) });
-    const decisionResult: ApprovalGuardDecision = { allowed: decision === "allow", brokered: true, receipt: clone(receipt),
+    const decisionResult: ApprovalGuardDecision = { allowed: decision === "allow", brokered: true, receipt: clone(receipt), choice,
       consume: () => this.#consume(binding, receipt), cancel: (reason = "guard-cancelled") => this.#cancelPermit(binding, receipt, reason) };
     pending.resolve(decisionResult);
     if (decision === "deny") this.#finish(binding, pending, receipt);
@@ -323,7 +340,7 @@ export class PiApprovalBroker {
       deduplicated: false, auditRef: ref("approval-audit", binding.secret, [approvalRef, resolvedAt, surface]), executor: "pi-guard", directExecution: false };
     pending.receipt = receipt; binding.recent.push(receipt); binding.recent = binding.recent.slice(-MAX_RECENT);
     this.#emit(binding, { kind: state === "expired" ? "expired" : "cancelled", approvalRef, receipt: clone(receipt) });
-    pending.resolve({ allowed: false, brokered: true, receipt: clone(receipt), consume: () => false, cancel: () => undefined }); this.#finish(binding, pending, receipt);
+    pending.resolve({ allowed: false, brokered: true, receipt: clone(receipt), choice: "deny", consume: () => false, cancel: () => undefined }); this.#finish(binding, pending, receipt);
   }
 
   #finish(binding: Binding, pending: Pending, receipt: Receipt): void {