Skip to content

Active Rewrite Workflow

Active rewrite is Seam's main offensive path. It applies YAML rules to complete decoded messages and records before, after, and rule_applied.

Start A Proxy

seam proxy --listen 127.0.0.1:8400 \
  --upstream http://127.0.0.1:8500 \
  --rules rules/a2a_prompt_laundering_replace.yaml \
  --transcript rewrite.json \
  --schema schemas/transcript.schema.json \
  --expect-min-rewrites 1 \
  --summary-json rewrite.summary.json

Tail the session:

seam session tail --transcript rewrite.json --limit 10

Explain the rule:

seam rules explain --rules rules/a2a_prompt_laundering_replace.yaml \
  --rule a2a_prompt_laundering_replace

Trace after the run:

seam rules trace --rules rules/a2a_prompt_laundering_replace.yaml \
  --transcript rewrite.json

Expected Transcript Shape

seq=3 a2a/message request id=req-7 rule=a2a_prompt_laundering_replace hash=<hash>

A rewrite record should have:

  • before: decoded original message
  • after: decoded mutated message
  • rule_applied: the rule id
  • hash: the post-record chain hash

If rule_applied is missing, the message was captured but not rewritten.

Debugging No Matches

Use this order:

  1. seam transcript inspect --decoded to confirm the decoded path exists.
  2. seam rules explain to confirm the intended touched path.
  3. seam rules test against a fixture to prove the rule can match at all.
  4. seam rules trace to see why records did not match.
  5. Confirm the message was complete and eligible for rewrite.
  6. Confirm you started proxy, not tap.

Injection Rules

For practical injection, use the rule primitive that matches the target shape:

  • insert: add a message part, task artifact, Agent Card skill, or tool-result item at a known array index.
  • merge: add nested fields to MCP tool-call arguments or A2A metadata without replacing the whole object.
  • replace: alter one string field with regex captures.
  • append: add to the end of an existing or newly created list.
  • set: force one decoded path to one value.

Example insertion rule:

seam rules test \
  --rules rules/a2a_message_part_insert.yaml \
  --fixture examples/a2a-message-send.json \
  --expect-rule a2a_message_part_insert \
  --json