@piagent/platform 1.47.0 → 1.48.1

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.1",
   "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 {

package/packages/piagent-core/runtime/inspection/runtime-event-store.ts

@@ -252,7 +252,11 @@ export class RuntimeEventStore {
     const flags = fs.constants.O_WRONLY | fs.constants.O_APPEND | (fs.constants.O_NOFOLLOW ?? 0)
       | (creating ? fs.constants.O_CREAT | fs.constants.O_EXCL : 0);
     const descriptor = fs.openSync(target, flags, 0o600);
-    try { fs.writeFileSync(descriptor, `${JSON.stringify(event)}\n`); fs.fsyncSync(descriptor); fs.fchmodSync(descriptor, 0o600); } finally { fs.closeSync(descriptor); }
+    // No fsync: it ran for every event, Terminal sessions included, and three of
+    // them sat between Enter and the message showing. A store belongs to one
+    // runtime instance, and one left damaged by a power cut only sends the
+    // dashboard back to a snapshot (resyncRequired).
+    try { fs.writeFileSync(descriptor, `${JSON.stringify(event)}\n`); fs.fchmodSync(descriptor, 0o600); } finally { fs.closeSync(descriptor); }
     segment.count += 1; this.events.push(event); this.eventById.set(event.eventId, event);
     if (candidate) this.emissionGuard.recordAccepted(candidate);
     try { this.enforceRetention(); } catch { this.corruptions.push("event-retention-failed"); }

package/packages/piagent-core/runtime/policy/handoff-policy.mjs

@@ -0,0 +1,144 @@
+// What every permission mode still asks about, Bypass included (owner,
+// 2026-10-29: "Bypass bypasses the work and stops at the handoff").
+//
+// handoffReason: the work leaves this machine. A push, a pull request or a
+// merge, a release, a package publish, a deploy, a registry push or login, a
+// remote shell, a cloud or cluster tool, an upload. Asked in every mode, in
+// personal and company sessions alike.
+// mustConfirm: the handoff plus what is destructive or irreversible here:
+// database migrations, deletes whose target is only known at run time,
+// removing Docker volumes, sudo. Asked in Full access; Bypass runs these.
+//
+// Both read the command twice: through the shared scanner (policy-core.js)
+// and through a shell syntax tree (extensions/shell-ast.js), which also finds
+// commands in functions, case arms, heredoc substitutions and `bash -c` text.
+// `git -C api push`, `env X=1 git push` and `cd api && git push` are one push.
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { evaluateExecPolicyCore, stripWrapper } from '../../extensions/policy-core.js';
+import { gitSubcommandWords } from '../../extensions/shell-command-words.js';
+import { astCommands } from '../../extensions/shell-ast.js';
+
+export { stripWrapper };
+
+const POLICY = JSON.parse(fs.readFileSync(fileURLToPath(new URL('../../policies/base-policy.json', import.meta.url)), 'utf8'));
+// Local, reversible exec-policy prompts that Full access runs without asking
+// (personal and company sessions).
+export const FULL_ACCESS_RUNS = new Set(['prompt-git-add-broad']);
+// requireConfirmationPatterns that are not a handoff: they stay with mustConfirm.
+const LOCAL_PATTERNS = new Set(['migration']);
+// Tools that reach other machines or accounts.
+const REMOTE = new Set(['ssh', 'scp', 'sftp', 'vercel', 'netlify', 'fly', 'flyctl', 'heroku', 'firebase', 'aws', 'gcloud', 'gsutil', 'az',
+  'kubectl', 'helm', 'terraform', 'tofu', 'pulumi', 'eas', 'wrangler', 'supabase', 'railway', 'render', 'doctl']);
+// Package runners: the package they run is the command (`npx vercel deploy`).
+const RUNNERS = new Set(['npx', 'bunx', 'pnpx']);
+// Commands that run the command after them, with the options that take a value.
+const LAUNCHERS = new Map([['timeout', new Set(['-s', '--signal', '-k', '--kill-after'])], ['xargs', new Set(['-I', '-n', '-P', '-L', '-d', '-s', '-E', '-a'])],
+  ['watch', new Set(['-n', '--interval', '-d'])], ['caffeinate', new Set(['-t', '-w'])]]);
+const PUBLISHERS = [['cargo', 'publish'], ['twine', 'upload'], ['gem', 'push'], ['pod', 'trunk', 'push'], ['dotnet', 'nuget', 'push'], ['mvn', 'deploy'],
+  ['gradle', 'publish'], ['gradlew', 'publish'], ['poetry', 'publish'], ['uv', 'publish'], ['flutter', 'pub', 'publish'], ['dart', 'pub', 'publish'], ['vsce', 'publish'], ['ovsx', 'publish']];
+
+const parse = command => evaluateExecPolicyCore(String(command), { policy: POLICY, mode: 'enforce' });
+const quote = word => /^[A-Za-z0-9_@%+=:,./-]+$/.test(word) ? word : `'${String(word).replace(/'/g, `'"'"'`)}'`;
+// What the syntax tree finds that the scanner may not: each command it reads,
+// checked by the same exec policy as a line of its own.
+function treeFindings(command) {
+  const commands = astCommands(command) ?? [];
+  return commands.map(({ words }) => ({ words, result: words.length ? parse(words.map(quote).join(' ')) : null }));
+}
+// The simple commands a shell line runs, as both readers see them (inline
+// `bash -c`, substitutions and compound statements included).
+export const commandSegments = command => [...parse(command).segments, ...(astCommands(command) ?? []).map(({ words }) => ({ command: words.join(' '), words }))];
+
+function executable(words) {
+  let current = stripWrapper(words);
+  for (;;) {
+    if (RUNNERS.has(current[0]) || (['pnpm', 'yarn'].includes(current[0]) && current[1] === 'dlx')) {
+      current = current.slice(current[0] === 'pnpm' || current[0] === 'yarn' ? 2 : 1);
+      while (current[0]?.startsWith('-')) current = current.slice(1);
+    } else if (LAUNCHERS.has(current[0])) {
+      const valued = LAUNCHERS.get(current[0]), duration = current[0] === 'timeout';
+      current = current.slice(1);
+      while (current[0]?.startsWith('-')) current = current.slice(valued.has(current[0]) ? 2 : 1);
+      if (duration) current = current.slice(1);
+    } else break;
+    current = stripWrapper(current);
+  }
+  return gitSubcommandWords(current);
+}
+const positional = args => args.filter(arg => !arg.startsWith('-'));
+
+function segmentHandoff(words) {
+  const [name, ...args] = executable(words);
+  const sub = positional(args);
+  if (!name) return null;
+  if (REMOTE.has(name)) return `${name} reaches another machine or account`;
+  if (name === 'git') {
+    if (words.some((word, index) => (word === '-c' && /^alias\./i.test(words[index + 1] ?? '')) || /^-calias\./i.test(word))) return 'git runs an alias defined in the command';
+    if (['push', 'send-email', 'request-pull'].includes(sub[0])) return `git ${sub[0]} sends to a remote`;
+    if (['subtree', 'lfs'].includes(sub[0]) && sub[1] === 'push') return `git ${sub[0]} push sends to a remote`;
+    return null;
+  }
+  if (name === 'rsync' && args.some(arg => /^[^/\s]*:/.test(arg) && !arg.startsWith('-'))) return 'rsync to another machine';
+  if (['docker', 'podman'].includes(name)) {
+    if (['push', 'login'].includes(sub[0])) return `${name} ${sub[0]} sends to a registry`;
+    if (args.includes('--push')) return `${name} build --push sends to a registry`;
+    return null;
+  }
+  if (['npm', 'pnpm', 'yarn', 'bun'].includes(name) && (sub[0] === 'publish' || (sub[0] === 'npm' && sub[1] === 'publish'))) return `${name} publish uploads a package`;
+  const publisher = PUBLISHERS.find(entry => entry[0] === name.replace(/^\.\//, '') && entry.slice(1).every((word, index) => sub[index] === word));
+  if (publisher) return `${publisher.join(' ')} uploads a package`;
+  return null;
+}
+
+// Why this command hands the work off (asked in every mode), or null.
+export async function handoffReason(command) {
+  const result = parse(command);
+  const pattern = result.reasons.find(reason => reason.startsWith('Confirmation required: the command runs ')
+    && !LOCAL_PATTERNS.has(reason.slice('Confirmation required: the command runs '.length)));
+  if (pattern) return pattern;
+  const tree = treeFindings(command);
+  for (const segment of [...result.segments, ...tree]) {
+    const reason = segmentHandoff(segment.words);
+    if (reason) return reason;
+  }
+  for (const { result: found } of tree) {
+    const reason = found?.reasons.find(item => item.startsWith('Confirmation required: the command runs ') && !LOCAL_PATTERNS.has(item.slice('Confirmation required: the command runs '.length)));
+    if (reason) return reason;
+  }
+  const { findShellExternalConfirmationReason } = await import('../../extensions/guard-shell-analysis.ts');
+  const segments = [...result.segments, ...tree.flatMap(({ result: found }) => found?.segments ?? [])];
+  return findShellExternalConfirmationReason(segments, { defaultMode: 'enforce', ...POLICY.externalActionPolicy }) ?? null;
+}
+
+// What the syntax tree finds that the scanner let through: a refused or asked
+// command hidden in a function, a case arm or a heredoc substitution. The
+// personal guard and Full access add it to what the scanner decided.
+export function treeExecFinding(command) {
+  for (const { result } of treeFindings(command)) {
+    if (result && result.decision !== 'allow' && result.reasons.length) return { decision: result.decision, reason: result.reasons[0] };
+  }
+  return null;
+}
+
+// Why Full access must still ask about this command, or null.
+export async function mustConfirm(command) {
+  const handoff = await handoffReason(command);
+  if (handoff) return handoff;
+  const result = parse(command);
+  const kept = result.reasons.filter(reason => ![...FULL_ACCESS_RUNS].some(id => reason.startsWith(`Prompt required by exec policy ${id}:`)));
+  if (result.decision !== 'allow' && kept.length) return kept[0];
+  const tree = treeExecFinding(command);
+  if (tree && ![...FULL_ACCESS_RUNS].some(id => tree.reason.startsWith(`Prompt required by exec policy ${id}:`))) return tree.reason;
+  if (result.segments.some(segment => ['sudo', 'doas'].includes(segment.words.find(word => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(word))))) return 'sudo runs as another user';
+  return null;
+}
+
+// Whether an MCP tool writes to the system behind its server, read from the
+// tool's name with the verbs personal Piagent's guard uses
+// (base-policy.json externalActionPolicy): the verb, or null.
+export async function mcpWriteAction(tool) {
+  const { actionTokens, classifyActionTokenSequence } = await import('../../extensions/guard-shell-analysis.ts');
+  const result = classifyActionTokenSequence(actionTokens(String(tool)), { defaultMode: 'enforce', ...POLICY.externalActionPolicy });
+  return result.kind === 'write' ? result.action : null;
+}

package/packages/piagent-core/runtime/registration/permission-commands.ts

@@ -65,10 +65,10 @@ export function registerPermissionCommands(pi: ExtensionAPI, deps: Record<string
     ctx.ui.notify(message, level);
     if (permissionProfile.warning) ctx.ui.notify(permissionProfile.warning, "warning");
     if (permissionProfile.mode === "trusted-full-access") {
-      ctx.ui.notify("Trusted full access is active; protected paths, secret redaction, and destructive/external confirmations remain enforced.", "warning");
+      ctx.ui.notify("Trusted full access is active; protected paths, secret redaction, and destructive and handoff confirmations remain enforced.", "warning");
     }
     if (permissionProfile.mode === "bypass") {
-      ctx.ui.notify("Bypass is active: nothing is asked or blocked in this personal session (deletes, pushes, protected paths included). Output redaction and /undo checkpoints remain. Company sessions keep their own rules.", "warning");
+      ctx.ui.notify("Bypass is active: the work is not asked about or blocked in this personal session (deletes and protected paths included). The handoff (push, PR, publish, deploy, remote tools, MCP writes) is still asked; output redaction and /undo checkpoints remain. Company sessions keep their own rules.", "warning");
     }
     emitPermissionStatus(ctx, permissionProfile);
     if (request.trim()) sendWorkflowFollowUp(request.trim());

package/packages/piagent-core/runtime/solver/runtime-features.ts

@@ -1,3 +1,5 @@
+import { execFile } from "node:child_process";
+
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import { gitEvidenceRootDetails, workingTreeHasChanges } from "../../extensions/workspace-evidence-roots.js";
@@ -8,17 +10,57 @@ import type { TaskFeatureInput } from "./task-features.ts";
 import type { SolverShadowEvaluation } from "./solver-shadow.ts";
 import { SolverShadowRuntime } from "./solver-shadow.ts";
 
-// Finding the repositories under a parent folder runs Git once per child and
-// blocks the terminal; they rarely change between two prompts.
-const ROOTS_TTL_MS = 30_000;
-const rootDetails = new Map<string, { at: number; details: ReturnType<typeof gitEvidenceRootDetails> }>();
-function gitShape(cwd: string): { gitReady: boolean; dirtyTree: boolean } {
-  let cached = rootDetails.get(cwd);
-  if (!cached || Date.now() - cached.at > ROOTS_TTL_MS) {
-    try { cached = { at: Date.now(), details: gitEvidenceRootDetails(cwd) }; } catch { return { gitReady: false, dirtyTree: true }; }
-    rootDetails.set(cwd, cached);
+type GitShape = { gitReady: boolean; dirtyTree: boolean };
+
+function readGitShape(cwd: string): GitShape {
+  try {
+    const details = gitEvidenceRootDetails(cwd);
+    return { gitReady: details.roots.length > 0, dirtyTree: workingTreeHasChanges(cwd, details) };
+  } catch { return { gitReady: false, dirtyTree: true }; }
+}
+
+// The Git shape runs `git rev-parse` (once per child repository in a parent
+// folder) and `git status`. Read synchronously on every prompt it held the
+// Terminal between Enter and the message showing, longer the larger the
+// repository. It is now read in a child process when the session starts and
+// after each run, and a prompt takes the last answer. Only a prompt with no
+// answer yet reads it inline, as before.
+const SHAPE_FRESH_MS = 5_000;
+const SHAPE_PROBE = `import(${JSON.stringify(new URL("../../extensions/workspace-evidence-roots.js", import.meta.url).href)}).then((git) => {
+  let shape; try { const details = git.gitEvidenceRootDetails(process.argv[1]);
+    shape = { gitReady: details.roots.length > 0, dirtyTree: git.workingTreeHasChanges(process.argv[1], details) };
+  } catch { shape = { gitReady: false, dirtyTree: true }; }
+  process.stdout.write(JSON.stringify(shape));
+});`;
+const shapes = new Map<string, { at: number; shape: GitShape }>();
+const probing = new Map<string, Promise<void>>();
+
+export function refreshGitShape(cwd: string): Promise<void> {
+  const running = probing.get(cwd);
+  if (running) return running;
+  const startedAt = Date.now();
+  const probe = new Promise<void>((resolve) => {
+    execFile(process.execPath, ["--input-type=module", "-e", SHAPE_PROBE, cwd], { timeout: 60_000, maxBuffer: 4096, windowsHide: true }, (error, stdout) => {
+      try {
+        const shape = JSON.parse(String(stdout)) as GitShape;
+        if (!error && typeof shape.gitReady === "boolean" && typeof shape.dirtyTree === "boolean") shapes.set(cwd, { at: startedAt, shape });
+      } catch { /* the next prompt reads it inline */ }
+      resolve();
+    });
+  }).finally(() => probing.delete(cwd));
+  probing.set(cwd, probe);
+  return probe;
+}
+
+function gitShape(cwd: string): GitShape {
+  const cached = shapes.get(cwd);
+  if (!cached) {
+    const shape = readGitShape(cwd);
+    shapes.set(cwd, { at: Date.now(), shape });
+    return shape;
   }
-  return { gitReady: cached.details.roots.length > 0, dirtyTree: workingTreeHasChanges(cwd, cached.details) };
+  if (Date.now() - cached.at > SHAPE_FRESH_MS) void refreshGitShape(cwd);
+  return cached.shape;
 }
 
 export function runtimeTaskFeatureInput(options: {