Follow-up: tighten WriteStdin authorization and delivery semantics

[M4n5ter]

English

Context

#778 adds interactive PTY control through WriteStdin. Its review confirmed the merge-blocking contract and identified four related, non-blocking follow-ups at the boundary between model intent, user authorization, and PTY driver guarantees.

This issue tracks only those four follow-ups. It does not propose growing #778 or reopening its accepted canonical-audit decisions.

Problems

1. Permission inspection is less complete than the authorized side effect

Activity rows intentionally use a bounded, redacted inputPreview. The same projection currently reaches the permission UI, including its "view full parameters" surface. A WriteStdin call may contain up to 64 KiB, so a meaningful suffix can be outside the 160-character preview.

For example, a long diagnostic prefix and a later destructive command can share the same visible preview. The user would be authorizing the complete input while only being able to inspect its prefix.

The activity projection should remain bounded and redacted. The permission surface should instead offer a deliberate full-input inspector that:

• displays the exact input as escaped text rather than interpreting terminal control sequences;
• shows the target ref and resize, when present;
• keeps the compact preview as the default view.

2. Turn memory is not bound to terminal state

The permission scope now includes the complete ref + input + size, which prevents different inputs from sharing approval. It does not make repeated bytes equivalent across terminal states: approving y\r for one prompt may currently authorize the same bytes at a later, unrelated prompt on the same PTY.

The smallest safe direction is to disable turn-level permission memory for WriteStdin. An optimistic concurrency contract such as expectedRevision may be useful later, but it should be considered separately rather than required to close the immediate authorization gap.

3. input.applied claims more than the driver can observe

node-pty exposes write(data): void. A non-throwing call establishes that the driver accepted or queued the write request; it does not prove that the target process received or consumed every byte.

The operation result should therefore use queued, which describes the driver's asynchronous handoff without claiming delivery. Resize semantics are separate and need not be weakened because the resize API exposes a different observable contract.

4. ref validation is stricter at execution than at the schema and presentation boundaries

Runtime execution already parses the canonical maka://runtime/background-tasks/... resource format and rejects malformed refs. The public WriteStdin schema still accepts an unbounded string, and the human-facing projection copies that string without a bound.

The schema, projection, and runtime parser should share one bounded ref contract so malformed or oversized values fail before permission and cannot expand UI or telemetry payloads.

Proposed boundary

• Canonical tool-call history continues to retain exact model-generated arguments, including denied calls.
• Activity cards and ordinary transcript rows continue to use the bounded, redacted projection.
• Permission inspection can reveal the full exact input only through an explicit, safely escaped inspector.
• WriteStdin does not reuse permission across terminal states through turn memory.
• Tool results describe only what the PTY driver can actually guarantee.
• The canonical runtime-resource parser remains the source of truth for valid refs and is reused at earlier boundaries where practical.

Implementation direction

• Restore the common meaning of PermissionRequest.args: the exact invocation being authorized. WriteStdin should no longer replace it with the activity projection in the permission engine. The Desktop and TUI permission surfaces derive their bounded summary from those exact args; the expanded view renders the full input as inert escaped text. No second inspector payload is needed.
• Disable turn memory for WriteStdin at the permission-policy boundary, and hide or disable the corresponding UI control. All clients should receive the same rule rather than relying on a TUI-only exception.
• Rename operation.input.applied to operation.input.queued. A non-throwing node-pty.write() means the write entered the driver's asynchronous path, not that the child process received it.
• Reuse the canonical shell-run ref validator in the WriteStdin schema, add a length bound derived from the canonical format, and bound the defensive human projection independently.
• Treat revision-bound control as a separate enhancement. It is not required to remove unsafe turn-memory reuse and should not expand this follow-up.

The permission-facing changes and runtime-contract changes can be delivered as separate, independently reviewable PRs under this issue.

Planned PR split

• Permission boundary: restore exact PermissionRequest.args, derive the bounded summary and full escaped inspector in Desktop/TUI, and disable WriteStdin turn memory at both policy and UI boundaries.
• Runtime contract: rename input applied to queued, validate the canonical shell-run ref in the tool schema, and keep its defensive human projection bounded.

Acceptance criteria

• A user can inspect the complete exact input, plus the target ref and resize, before approving a WriteStdin side effect.
• ANSI escapes and control characters in the full inspector are rendered as inert escaped text.
• Approving one WriteStdin call does not silently authorize the same bytes at a later terminal state.
• A successful input operation reports that the input was queued, without claiming end-to-end delivery.
• Malformed and oversized refs are rejected by the tool schema and remain bounded in human-facing projections.
• The compact activity-card experience remains bounded and redacted.

Follow-up to #778.

简体中文

背景

#778 通过 WriteStdin 增加了交互式 PTY 控制。审查确认了阻断合并的契约已经落实，同时指出四项彼此相关、但不阻断本次合并的后续问题。它们都位于模型意图、用户授权与 PTY driver 保证之间的边界。

本 issue 只跟踪这四项后续工作，不建议继续扩大 #778，也不重新讨论其中已经确认的 canonical 审计决策。

问题

1. 权限检查展示的信息少于实际授权的副作用

Activity 行有意使用有界、脱敏的 inputPreview。目前同一投影也会进入权限 UI，包括“查看完整参数”界面。一次 WriteStdin 最多可以包含 64 KiB 输入，因此有意义的后缀可能位于 160 字预览之外。

例如，一段很长的诊断前缀之后可以跟随另一个具有破坏性的命令，而两者在权限框中只显示相同的前缀。用户实际上批准的是完整输入，却无法检查完整输入。

Activity 投影应继续保持有界和脱敏；权限界面则应提供一个需要用户主动展开的完整输入检查器，并满足：

• 把精确输入显示为转义后的普通文本，不解释终端控制序列；
• 显示目标 ref，以及存在时的 resize；
• 默认仍显示紧凑预览。

2. 回合内授权记忆没有绑定终端状态

权限 scope 已包含完整的 ref + input + size，因此不同输入不会再共享授权。但相同字节在不同终端状态下并不具有相同语义：为一个提示批准 y\r，目前可能使同一 PTY 在稍后另一个无关提示中自动放行相同字节。

最小且稳妥的方向是禁用 WriteStdin 的回合内授权记忆。将来可以单独讨论 expectedRevision 一类乐观并发契约，但不应把它作为关闭眼前授权缺口的前置条件。

3. input.applied 超出了 driver 能够观察到的保证

node-pty 暴露的是 write(data): void。调用未抛异常只能说明 driver 接受或排队了写入请求，不能证明目标进程已经收到或消费了每一个字节。

因此，操作结果应采用 queued，表达写入已经进入 driver 的异步路径，但不声称已经送达。Resize 的可观察契约不同，不需要因为输入语义的调整而一并弱化。

4. ref 在执行边界的验证严于 schema 与展示边界

Runtime 执行前已经解析 canonical maka://runtime/background-tasks/... 资源格式并拒绝畸形 ref，但公开的 WriteStdin schema 仍接受无界字符串，人类可见投影也会无界复制该字符串。

Schema、投影和 runtime parser 应共享同一个有界 ref 契约，使畸形或超长输入在进入权限流程前失败，并且不能放大 UI 或 telemetry payload。

建议边界

• Canonical 工具调用历史继续保留模型生成的精确参数，包括被拒绝的调用。
• Activity 卡片和普通 transcript 行继续使用有界、脱敏的投影。
• 只有用户主动展开权限检查器时，才以安全转义形式展示完整精确输入。
• WriteStdin 不通过回合内授权记忆跨终端状态复用权限。
• 工具结果只描述 PTY driver 实际能够保证的事实。
• Canonical runtime-resource parser 继续作为合法 ref 的事实来源，并在合适的更早边界复用。

实现方向

• 恢复 PermissionRequest.args 的统一含义：它表示正在等待授权的精确调用。WriteStdin 不再由 permission engine 提前替换成 activity 投影。Desktop 与 TUI 权限界面从精确参数派生有界摘要，展开视图则把完整输入渲染为不可执行的转义文本；不需要新增第二套 inspector payload。
• 在 permission policy 边界统一禁用 WriteStdin 的 turn memory，并隐藏或禁用相应 UI 控件。所有客户端遵循同一规则，不加入只对 TUI 生效的例外。
• 将 operation.input.applied 重命名为 operation.input.queued。node-pty.write() 未抛异常只表示写入进入 driver 的异步路径，不表示子进程已经收到输入。
• 在 WriteStdin schema 中复用 canonical shell-run ref validator，按 canonical 格式推导长度上限，并让防御性的人类投影独立保持有界。
• 将 revision-bound control 作为独立增强处理。它不是消除不安全 turn-memory 复用的前置条件，也不应扩大本 follow-up。

权限侧修改与 runtime 契约修改可以在本 issue 下拆成两个彼此独立、易于审查的 PR。

计划的 PR 拆分

• 权限边界： 恢复精确的 PermissionRequest.args，在 Desktop/TUI 中派生有界摘要与完整转义检查视图，并在 policy 和 UI 两层禁用 WriteStdin turn memory。
• Runtime 契约： 将输入的 applied 重命名为 queued，在 tool schema 中验证 canonical shell-run ref，并保持防御性的人类投影有界。

验收条件

• 用户在批准 WriteStdin 副作用前，可以检查完整精确输入、目标 ref 和 resize。
• 完整检查器把 ANSI escape 与控制字符显示为不可执行的转义文本。
• 批准一次 WriteStdin 不会在稍后的终端状态中静默放行相同字节。
• 成功结果只报告输入已进入队列，不声称已经端到端送达。
• 畸形和超长 ref 会被 tool schema 拒绝，并且在人类可见投影中始终有界。
• 紧凑 activity 卡片继续保持有界和脱敏。

#778 的后续跟进。

[M4n5ter]

English

Hi @Astro-Han,

While validating a first-pass implementation of the permission-boundary work, I encountered several constraints that were not explicit in the original issue. I would like to confirm them here before opening any PR.

The linked snapshot only provides a concrete reference for the findings below. It is not the proposed final PR shape, and I may split the general fixes into independent PRs based on this discussion.

1. Exact arguments also need value semantics

Passing complete arguments through PermissionRequest.args is insufficient if the same mutable object crosses persistence, event, permission, and execution ownership boundaries.

In the AI SDK path, an external consumer could otherwise mutate nested argument state after the permission request was inspected, causing the authorized value and the executed value to differ.

The Pi path has a related protocol boundary: permission_request and tool_start are separate frames. Repeated frames for the same toolUseId must not be able to change the tool name or arguments after the invocation has been established.

The reference implementation uses this invariant:

A tool invocation has value semantics. Runtime/backend retains a private canonical argument snapshot, and external owners receive independent copies. In Pi, the first accepted frame for a toolUseId establishes that snapshot; later frames must agree or fail closed as a protocol error.

This is a general Runtime/backend guarantee rather than a WriteStdin presentation detail. It also introduces several structuredClone operations at ownership boundaries instead of sharing one mutable object, so I would like to confirm whether this is the intended ownership model.

2. Turn memory becomes a request capability

A UI-only toolName === 'WriteStdin' exception would still leave other clients able to submit rememberForTurn.

The reference implementation places canRememberForTurn on each PermissionRequest:

• shared policy sets it to false for WriteStdin;
• Desktop and TUI omit the memory control when the capability is unavailable;
• Runtime rejects an allowed response that attempts to establish memory without that capability.

This keeps the restriction in the shared permission contract instead of duplicating tool-specific policy across clients.

3. Disabling memory exposes the TUI single-slot permission problem

The TUI currently retains one pending permission request. Concurrent requests can overwrite one another, leaving an earlier tool permanently parked.

Turn memory could sometimes hide this by resolving another request with the same remembered scope. Once WriteStdin memory is disabled, that accidental release path no longer exists.

Desktop already maintains a per-session FIFO permission queue. The reference implementation gives the TUI corresponding request-ID FIFO behavior. I consider this a general permission correctness fix rather than additional PTY functionality.

Possible PR decomposition

The two behavioral groups originally listed in this issue do not necessarily need to map to exactly two PRs. The implementation can be divided into independently useful changes:

1. General canonical argument ownership, including Pi repeated-frame consistency.
2. General TUI permission-request FIFO handling.
3. WriteStdin permission inspection and turn-memory policy.
4. Runtime contract changes for queued semantics and bounded canonical ref validation.

My current preference is to submit the general fixes independently if their contracts are accepted, then build the smaller WriteStdin permission change on top. The runtime-contract work remains independent and unchanged.

Does the canonical value-semantics invariant above match the intended Runtime design? If so, would separate prerequisite PRs for canonical ownership and TUI FIFO be preferable to including them in the WriteStdin permission PR?

No PR has been opened yet. I wanted to bring these implementation findings back to the issue before choosing the final split.

简体中文

在验证权限边界的第一版实现时，我遇到了几项原 issue 没有明确表达的约束。我希望在发起 PR 前先在这里确认这些问题。

该快照只用于具体佐证下述实现发现，并不代表最终 PR 的组织形式。我可能根据讨论结果，将其中的通用修复拆成独立 PR。

1. 精确参数还需要值语义

仅让 PermissionRequest.args 携带完整参数并不足以保证授权正确。如果同一个可写对象跨越持久化、事件、权限与执行等所有权边界，外部消费者仍可能在用户检查权限请求后修改其中的嵌套参数，导致实际授权的值与最终执行的值不同。

Pi 路径还存在一个相关的协议边界：permission_request 与 tool_start 是独立帧。同一 toolUseId 的后续帧不应在调用已经确定后改变工具名称或参数。

第一版实现采用了以下不变量：

一次工具调用的参数具有值语义。Runtime/backend 保留私有 canonical 参数快照，外部所有者取得独立副本。在 Pi 中，同一 toolUseId 的首个已接受帧建立该快照；后续帧必须与其一致，否则作为协议错误 fail closed。

这是一项通用的 Runtime/backend 保证，而不是 WriteStdin 特有的展示细节。它也会在各所有权边界执行数次 structuredClone，而不是共享同一个可写对象，因此我希望确认这是否符合预期的所有权模型。

2. Turn memory 成为请求级能力

只在 UI 中判断 toolName === 'WriteStdin'，仍然无法阻止其它客户端提交 rememberForTurn。

第一版实现改为在每个 PermissionRequest 上携带 canRememberForTurn：

• 共享 policy 为 WriteStdin 设置 false；
• Desktop 与 TUI 在该能力不可用时不显示 memory 控件；
• Runtime 拒绝没有该能力却试图为已允许调用建立 memory 的响应。

这样可以把限制保留在共享权限契约中，而不需要各客户端分别复制工具特例。

3. 禁用 memory 暴露了 TUI 的单槽权限问题

TUI 目前只保留一个 pending permission request。并发请求可能互相覆盖，使较早的工具永久停在 parked 状态。

Turn memory 有时会通过相同 remembered scope 顺带释放另一个请求，从而掩盖这个问题。正确禁用 WriteStdin memory 后，这条偶然的释放路径不再存在。

Desktop 已经维护按 session 隔离的 FIFO 权限队列。第一版实现让 TUI 同样按 request ID 使用 FIFO。我认为这是通用权限正确性修复，而不是额外增加 PTY 功能。

可能的 PR 拆分

Issue 中原本列出的两类行为不一定必须对应恰好两个 PR。实现可以拆分为以下彼此独立且有实际价值的修改：

1. 通用 canonical 参数所有权，包括 Pi 重复帧一致性。
2. 通用 TUI 权限请求 FIFO。
3. WriteStdin 权限检查与 turn-memory policy。
4. queued 语义和有界 canonical ref 验证的 runtime contract 修改。

如果这些通用契约得到认可，我目前倾向于先把通用修复分别提交，再在其上提交更小的 WriteStdin 权限改动。Runtime contract 修改仍保持独立，方向不变。

上述 canonical 值语义不变量是否符合预期的 Runtime 设计？如果认可，相比把它们包含在 WriteStdin 权限 PR 中，是否更适合先分别提交 canonical ownership 与 TUI FIFO 两个前置 PR？

目前尚未发起任何 PR。我希望先把第一版实现暴露出的这些情况带回 issue，再决定最终拆分方式。

[Astro-Han]

English

Thanks for bringing these findings back before opening a PR.

I think the value-semantics invariant is the right boundary. The permission contract should be simple: the value the user inspects must be the value Runtime executes. Runtime should retain one private canonical snapshot, while persistence, events, permission handling, and tool execution receive independent copies. For Pi, the first accepted frame for a toolUseId should establish that snapshot; any later mismatch should fail closed.

canRememberForTurn also looks like the smallest correct contract. Shared policy decides the capability, clients render it, and Runtime enforces it. A UI-only WriteStdin exception would leave a bypass.

The TUI single-slot behavior is a separate correctness bug. It should be fixed as a request-ID FIFO rather than folded into WriteStdin queue semantics.

The four-way split you proposed makes sense:

1. Canonical argument ownership and Pi frame consistency.
2. TUI permission FIFO.
3. WriteStdin inspection and turn-memory policy.
4. queued semantics and bounded canonical ref validation.

The first two should be separate prerequisite PRs. That keeps the WriteStdin permission change small, while the runtime-contract PR remains independent.

I would stop there for this issue. expectedRevision, a broader immutability layer, and a second inspector payload are not needed. Cloning at ownership boundaries is enough.

简体中文

感谢先把实现中发现的问题带回来。

我赞同这里的 value semantics。权限链路只需要守住一条硬约束：用户确认的参数，必须原样进入执行。Runtime 保留一份私有 canonical 快照，持久化、事件、权限和工具执行分别拿独立副本。Pi 侧由同一 toolUseId 的首个有效帧确定快照，后续帧不一致就直接失败。

canRememberForTurn 也是合适的最小扩展点：共享 policy 决定，客户端展示，Runtime 兜底校验。只在 UI 里特判 WriteStdin 会留下绕过路径。

TUI 单槽是一个独立的正确性问题，按 request ID 改成 FIFO 即可，不要把它做成 WriteStdin 专用逻辑。

建议按你提出的四项拆分：

1. Canonical 参数所有权与 Pi 帧一致性。
2. TUI permission FIFO。
3. WriteStdin 完整检查与 turn-memory policy。
4. queued 语义与有界 canonical ref 校验。

前两项适合作为独立的前置 PR。这样 WriteStdin 权限 PR 可以保持很小，runtime contract 也能独立推进。

这个 issue 到这里就够了。不需要加入 expectedRevision、通用不可变框架或第二套 inspector payload，在所有权边界复制参数即可。

[M4n5ter]

English

All work tracked by this issue has been merged:

• fix(runtime): preserve canonical tool argument ownership #884 preserves canonical tool-argument ownership and Pi frame consistency.
• fix(tui): queue concurrent permission requests #885 makes concurrent TUI permission handling a request-ID FIFO.
• fix(runtime): tighten WriteStdin delivery semantics and ref validation #965 implements precise queued delivery semantics and bounded canonical ref validation.
• fix: tighten WriteStdin permission boundary #966 completes exact WriteStdin inspection and disables turn-level permission memory at the shared policy and Runtime boundaries.

Together these changes satisfy the acceptance criteria. Broader additions such as expectedRevision, a general immutability layer, or a second inspector payload remain intentionally out of scope, as agreed.

Closing as completed.

简体中文

本 issue 跟踪的工作均已合并：

• fix(runtime): preserve canonical tool argument ownership #884 保证 canonical 工具参数的所有权与 Pi 帧一致性。
• fix(tui): queue concurrent permission requests #885 将 TUI 并发权限处理完善为按 request ID 管理的 FIFO。
• fix(runtime): tighten WriteStdin delivery semantics and ref validation #965 落实准确的 queued 送达语义与有界 canonical ref 校验。
• fix: tighten WriteStdin permission boundary #966 完成 WriteStdin 精确检查，并在共享 policy 与 Runtime 边界禁用回合内权限记忆。

这些修改共同满足了全部验收条件。按照已有共识，expectedRevision、通用不可变框架和第二套 inspector payload 等更大扩展仍明确不在本 issue 范围内。

以已完成状态关闭。