Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/coding-agents.md
Original file line number Diff line number Diff line change
Expand Up @@ -328,7 +328,7 @@ Code also a `systemMessage`, which it shows you, and the deny reason, which the
Why: uploading to cloud storage
Instead: Have a person approve the held call, or write the files locally and let a person upload them.
Person: look with `! tracekit approvals show apr-…`; allow once with `! tracekit approvals approve apr-…`; refuse with `! tracekit approvals reject apr-…`.
Agent: tell the person what this call was for and pass on these commands, then wait for their answer; a subagent puts them in its final report. Once it is approved, make the identical call again. If the Instead line is a step you can take yourself, you may take it and say so. Never hide what a call runs to get past the policy: every call is signed and kept.
Agent: ask the person: approve or skip? Don't reword around the hold, but do take an Instead step that's yours and say so; otherwise wait for their answer. Pass on the Person line and say what the call was for; a subagent puts both in its final report. Once it is approved, make the identical call again. Never hide what a call runs to get past the policy: every call is signed and kept.
```

A call the policy denies says so, in the same form, with no commands: no one can approve it.
Expand Down
2 changes: 1 addition & 1 deletion docs/quickstarts/claude-code.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ A held call doesn't run either, until you approve it. Claude Code shows the hold
Why: a quote on the line is never closed
Instead: Close the quote.
Person: look with `! tracekit approvals show apr-6f0c…`; allow once with `! tracekit approvals approve apr-6f0c…`; refuse with `! tracekit approvals reject apr-6f0c…`.
Agent: tell the person what this call was for and pass on these commands, then wait for their answer; ...
Agent: ask the person: approve or skip? Don't reword around the hold, but do take an Instead step that's yours and say so; ...
```

## 3. Answer it
Expand Down
34 changes: 31 additions & 3 deletions tests/test_hook_v2.py
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@

import adapter_contract as ac
from test_bundle_v2 import LOG_SECRET, ORIGIN, pub
from tracekit import cli, install, privacy
from tracekit import agent_hooks, cli, install, privacy
from tracekit.bundle_v2 import export
from tracekit.client import client_home
from tracekit.format.canon import event_hash
Expand All @@ -42,8 +42,10 @@
# an Instead step
OWN_STEP = ("If the Instead line is a step you can take yourself, you may take it and say so. Never hide what a call runs "
"to get past the policy: every call is signed and kept.")
HELD_AGENT = ("tell the person what this call was for and pass on these commands, then wait for their answer; a "
"subagent puts them in its final report. Once it is approved, make the identical call again. " + OWN_STEP)
HELD_AGENT = ("ask the person: approve or skip? Don't reword around the hold, but do take an Instead step that's yours "
"and say so; otherwise wait for their answer. Pass on the Person line and say what the call was for; a "
"subagent puts both in its final report. Once it is approved, make the identical call again. Never hide "
"what a call runs to get past the policy: every call is signed and kept.")
BLOCKED_AGENT = "tell the person what you were doing and why it was blocked. " + OWN_STEP


Expand Down Expand Up @@ -1871,6 +1873,32 @@ def test_by_default_a_held_call_is_blocked_at_once_with_how_to_approve_and_retry
self.assertEqual(json.loads(out), {"systemMessage": held, "hookSpecificOutput": {
"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": held}})

def test_a_held_call_asks_the_person_approve_or_skip(self):
"""#816: 63 of 70 holds in #815 expired, the agent rewording the call or moving on: the held message asks the
person one question, next to the command that approves the call, and says not to reword it around the hold."""
_, lines, _ = self.pre("force push.", wait="")
held = "\n".join(lines)
for said in ("`! tracekit approvals approve apr-1`", "ask the person: approve this call or skip it?",
"Don't reword the call to get past the hold; wait for their answer.", "Never hide what a call runs"):
self.assertIn(said, held)
self.assertNotIn("Instead", held)

def test_a_held_call_with_an_instead_step_lets_the_agent_take_it(self):
"""#816 review: TK-SHELL-PARSE, the most common hold, says to split the command into plain ones, and that is
what got through in #815; "don't reword the call" first, and the Instead step only at the end, told the agent
to stop doing it. With an Instead line the one rule says to take its step when it is the agent's own."""
_, lines, _ = self.pre("the parser can't read this command. Instead: Split it into plain commands; pipes, &&, "
"if, for, case and functions are read.", wait="")
held = "\n".join(lines)
self.assertIn("Don't reword around the hold, but do take an Instead step that's yours and say so; otherwise "
"wait for their answer.", held)
self.assertEqual(held.count("Instead step"), 1) # one rule, said once
# and both halves survive the 500 characters another harness's reply is cut to
out = io.StringIO()
agent_hooks._reply("codex", out, False, held.replace("! tracekit", "tracekit"), True)
cut = json.loads(out.getvalue())["hookSpecificOutput"]["permissionDecisionReason"]
self.assertIn("Don't reword around the hold, but do take an Instead step that's yours", cut)

def test_a_retry_in_an_agents_veto_delay_says_it_is_approved_and_how_long_to_wait(self):
"""An agent approver's approval reads `requested` while people may still revoke it: the held retry said to
approve it with `tracekit approvals approve`, an approval already approved. It says so, and to wait."""
Expand Down
19 changes: 13 additions & 6 deletions tracekit/integrations/claude_code.py
Original file line number Diff line number Diff line change
Expand Up @@ -205,13 +205,20 @@ def stopped(head, reason=None, person=None, agent=None):
"""What a call Tracekit stopped tells its agent and person, in every harness (each delivers it its own way: _block
for Claude Code, agent_hooks._reply for the others): `head` (with _rules), the signer's `reason` (Why) and, after
its INSTEAD, what to do instead; then `person`, the commands that answer a held call, and what the agent does
(`agent`, else: with `person`, pass them on and, once approved, make the identical call again; without, tell the
person). An Instead step may be the person's (check the payee before approving): the agent takes only its own."""
(`agent`, else: with `person`, ask them approve or skip and not reword the call around the hold, but take an
Instead step that is the agent's own, first since agent_hooks._reply may cut the end, and, once approved, make the
identical call again; without, tell the person). An Instead step may be the person's (check the payee before
approving): the agent takes only its own."""
why, _, instead = (reason or "").partition(INSTEAD)
agent = (agent or ("tell the person what this call was for and pass on these commands, then wait for their "
"answer; a subagent puts them in its final report. Once it is approved, make the identical call "
"again." if person else "tell the person what you were doing and why it was blocked.")) + (
" If the Instead line is a step you can take yourself, you may take it and say so." if instead else "")
own = " If the Instead line is a step you can take yourself, you may take it and say so." if instead else ""
if agent is None and person: # the Instead step is in the rule itself, inside _reply's 500 characters (#816 review)
agent = ("ask the person: approve or skip? Don't reword around the hold, but do take an Instead step that's "
"yours and say so; otherwise wait for their answer." if instead else
"ask the person: approve this call or skip it? Don't reword the call to get past the hold; wait for "
"their answer.") + (" Pass on the Person line and say what the call was for; a subagent puts both in "
"its final report. Once it is approved, make the identical call again.")
else:
agent = (agent or "tell the person what you were doing and why it was blocked.") + own
return "\n".join([f"[tracekit] {head}", *([f"Why: {why}"] if why else []),
*([f"Instead: {instead}"] if instead else []), *([f"Person: {person}"] if person else []),
f"Agent: {agent} Never hide what a call runs to get past the policy: every call is signed and "
Expand Down
Loading