Downstream requirements: the proposed "Pre-tool input rewrite" design

[PerryLink]

Downstream requirements: the proposed "Pre-tool input rewrite" design

This post collects requirements from a plugin that hits the current
pre-execute ceiling every day. It references the proposed agent note
.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md
(status: proposed; TODO(pre-tool-input-rewrite) anchors the missing phase).

The dsh-mask scenario (real, measured in our plugin workspace)

dsh-mask replaces PII with placeholders. Two of its hard rules matter here:
the agent/pre-step masking listener never blocks a step (it always calls
next()), and model-visible text equals the logged text. Its own source
records the ceiling: tool arguments cannot be rewritten at pre-execute
under the current contract, so the tools scope lands on results, "the
rewritable model-visible face" (dsh-mask index.mjs).

Consequence today: when the model emits a tool call whose arguments contain
PII (a bash command with an ID number, a key in an env assignment), those
arguments execute unmasked; masking happens only on the result content
post-execution. The only pre-execution lever tools/pre-execute offers is
allow/deny/ask over frozen arguments - for dsh-mask that means fail-closed
deny (blocks the work) or letting the plaintext run. What dsh-mask needs is
a pre-execution rewrite: replace secrets with placeholders and strip or
downgrade fields before execution, with the original arguments preserved
for audit.

Downstream view on the four open questions

Each item is a suggestion from one downstream, not a conclusion.

Q1. assistant/message rewrite vs a separate correction record.
Suggestion: default to a separate correction record carried into the next
request; keep the in-place rewrite as an explicit opt-in. Grounding:
permission-rules replays session history and keeps its decision rows
log-only, never injected into model context, precisely so the replay stays
faithful (dsh-permission-rules README). dsh-mask follows the same
invariant: the log must reconstruct exactly what the model saw. Editing the
assistant tool-call block changes what the model "sees it said"; the ADR's
own risk section notes a provider may reject that on replay.

Q2. Preserve the original arguments on tool/call (sidecar field)?
Suggestion: yes, under a reserved, schema-pinned field (for example
originalArguments). Audit needs both facts: what the model emitted and what
executed. Without the original, a post-hoc review cannot tell whether a
rewrite was the intended mask or a malicious edit, and the decision cannot
be reconstructed. Keep the sidecar out of presentation.

Q3. Where does the rewrite decision live?
Suggestion: a dedicated earlier extension point (a pre-rewrite decision)
over moving the existing pre-execute hook earlier. Moving the existing hook
forces every allow/deny/ask plugin to reason about a new ordering and can
make them run twice; a separate decision lets rewrite-only plugins such as
dsh-mask opt in while the existing gate keeps its firing point. The rewrite
must resolve before the log commit, and for deterministic maskers it should
complete synchronously without surfacing an ask.

Q4. Interaction with the permission ask flow.
Suggestion: ask binds to the effective (rewritten) arguments; the ask
payload shows the original-vs-effective difference so the human approves
exactly what will run. A decline must leave the original assistant/message
authoritative and execute nothing. A rewrite that changes the risk profile
must be visible as such, never silently folded into an approve.

What we will do with a merged mechanism

• dsh-mask: pre-execution argument masking/downgrade with originals
  preserved; retire the post-execution-only tools scope where the rewrite
  covers it.
• permission-rules: rewrite-aware audit rows; decision events record both
  argument forms.
• Report measured behavior (replay fidelity, audit completeness, ask flow)
  back to this discussion.

[jinyue806]

Second downstream use case: RTK token compression via updatedInput.command (real, verified on 0.1.5-rc.2)

This is a second, independent downstream hitting the exact same pre-execute ceiling as dsh-mask — sharing evidence for the proposed "Pre-tool input rewrite" design.

Scenario

RTK 0.49.0 (Rust Token Killer) is widely used in the Claude Code ecosystem to compress tool-call output. Its hook mode reads the PreToolUse payload from stdin and answers with hookSpecificOutput.updatedInput.command, i.e. it rewrites the command to rtk <cmd> before execution, cutting command output tokens by roughly 60–90%. It is a pure command-level rewrite — no model involvement, fully deterministic, single source of truth is rtk rewrite.

The same hook is trivial to wire in DSH: hooks.json with a PreToolUse entry whose command is rtk hook claude, and a bridge config pointing at it. We did exactly that against the shipped @deepseek-ai/dsh-hooks-claude-code bridge (v0.1.5-rc.2).

What we verified (source-level, not just behavior)

1. The bridge parses updatedInput but explicitly discards it: packages/hooks/hooks-claude-code/lib/index.js logs "hook requested updatedInput, which is not yet honored (ignored)".
2. ToolExecution.arguments are detached and frozen at creation (deepFreeze(detached)), and tools/pre-execute only returns allow / deny / ask — exactly the ordering/limitation Concrete downstream use case for a pre-commit tool-input rewrite consistency seam #1895 describes.
3. Net result: the hook command runs, but the rewritten command never reaches the executor. Confirmed on a restarted DSH Desktop with harness logs showing no bridge load trace and the Bash tool executing the original command unchanged.

Why this matters for the design

• The RTK use case is command output compression (token cost), dsh-mask is argument masking (PII). Both need the same mechanism: a pre-commit rewrite of tool input, with the effective value flowing to execution and the durable record.
• It adds a performance/economic motivation on top of the security one — a much larger adoption surface than PII masking alone, which may strengthen the case for promoting the proposed Agent Note.
• updatedInput is already the de-facto wire contract in the Claude Code hook ecosystem; honoring it in hooks-claude-code would immediately make a whole class of existing community hooks (RTK, CBM/context-mode, enforcement hooks, etc.) work in DSH unchanged.

Happy to validate the eventual contract against this use case (e.g. acceptance: one call, parallel calls, chained transforms, permission sees only effective input, replay fidelity) — same offer as in #1895.

[PerryLink]

Confirming your three claims at the current HEAD, and adding three facts that I think change how this should be scoped.

Your claims check out, verified against dsh-v0.1.6-alpha.2 @ ddefc45fbc (you verified on 0.1.5-rc.2; nothing has moved since):

• The warning is real and the string is exact — packages/hooks/hooks-claude-code/src/index.ts:174-175:

  if (output.updatedInput !== undefined) {
    ctx.logger.warn(`hooks-claude-code: ${point} hook requested updatedInput, which is not yet honored (ignored)`)
  }

• It is typed as ignored, not merely unimplemented. packages/hooks/hook-protocol/src/types.ts:132-136 documents the field as "A tool-input rewrite a hook requested (CC updatedInput). PARSED but NOT honored". The parse does happen — hook-protocol/src/codec.ts:131-132 copies it onto output.updatedInput — so the value survives the codec and dies at the bridge.
• arguments: deepFreeze(detached) is verbatim at packages/core/tools/src/index.ts:1423 (the same expression also at :640), so "detached and frozen at creation" is exactly right.

Three things I would add

1. The warning is deliberate and test-pinned. packages/hooks/hooks-claude-code/tests/coverage-cases.ts:113-128 is a test titled "warns and honors updatedInput as a no-op (input rewrite deferred)", and it asserts both halves:

expect((sawArgs as { command?: string }).command).toBe('original')
expect(warn).toHaveBeenCalledWith(expect.stringContaining('updatedInput'))

So honoring updatedInput is not adding a missing feature — it is flipping a contract that a test currently encodes the opposite of. Worth scoping that way, because that test is the acceptance criterion that has to change.

2. It is not one bridge. packages/hooks/hooks-codex/README.md:173 lists the same omissions — "additionalContext, permissionDecision: \"allow\", and updatedInput are ignored" — and adds that every tool is flattened to tool_input: { command }. So the real surface is "hook output the bridges parse but do not apply", which is why your whole class of existing community hooks framing is the right one and why a per-bridge fix would be the wrong shape.

3. Your ask is already an acceptance criterion of the Agent Note. .agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md:41 reads: "The CC/Codex bridges honor updatedInput instead of logging the faithful-but-degraded warning." Both bridges, named. And the reason for the warning is stated at :35: the bridge declines to claim the rewrite was honored. So this is not an oversight being rediscovered — it is a written criterion waiting on the consistency transaction, and the RTK case is a second independent consumer of it. That is the strongest form of evidence this thread can produce.

One vocabulary nuance, not a correction

"allow/deny/ask" is the Agent Note's own phrasing (:9, :29) and it is the right word for policy. The type itself has a fourth variant — packages/core/tools/src/index.ts:589-593:

export type PreToolDecision =
  | { kind: 'allow' }
  | { kind: 'deny'; reason: string; info?: ToolErrorInfo }
  | { kind: 'cancel' }
  | { kind: 'ask'; reason?: string }

cancel is the canonical before-dispatch result. It matters here only because a new rewrite decision must not become confusable with cancellation.

What the RTK case changes in the design

It is the deterministic, synchronous, single-source class — no model involvement, no human decision. Three consequences:

• A rewrite phase must stay ask-free for that class. If the transform is total and deterministic, surfacing an approval turns a pure function into a question.
• Ordering must be preserved. packages/core/tools/tests/ptc.spec.ts:703 pins "ordered pre-execute never overlaps: a slow policy on one call delays the next start". A chained-transform case has to hold that same guarantee: a rewrite phase inserted before the existing gate must not let two calls' transforms interleave.
• The cheapest independently landable increment is yours: honor updatedInput in the bridges. It needs no new plugin API and no change to PreToolDecision; it is acceptance criterion 3 on its own. The heavier consistency transaction — the three readers agreeing atomically — is only required once the rewrite has to reach assistant/message and tool/call. For a hook-driven command rewrite it does, which is exactly why the Note says extending PreToolDecision at its current firing point is insufficient (:29): by then both durable records already exist.

One thing I would keep separate: honoring updatedInput covers hook rewrites only. It gives plugin listeners no rewrite point at all. They can share one primitive, but conflating them would let a bridge-conformance fix stand in for the plugin-facing design.

On validating the contract

Your list — one call, parallel calls, chained transforms, permission sees only effective input, replay fidelity — maps almost onto the Note's own acceptance criteria (:37-41): all three readers agree atomically, ToolExecution.arguments stays deeply frozen throughout, and the warning is replaced rather than kept. I would add two:

• the executed value and the tool/call audit must both be inspectable, with the original arguments retained (the sidecar question); and
• an approval must bind to the effective arguments, so a person approves exactly what runs.

Happy to validate an alpha branch against real sessions in that shape — same offer as yours.