Repository navigation
Description
gptme plugins can deny a tool call before it runs (hooks, plugins). A TOOL_CONFIRM hook gets (tool_use, preview, workspace) and returns ConfirmationResult.skip(message) to deny the call (the message is the reason), confirm() to run it without asking, edit(content) to run changed content, or None to leave it to the next hook (hooks docs L177-209). Hooks run by priority, highest first, and a guardrail must out-rank the built-ins, the highest of which is guardrails at 200 (L211-235). --no-confirm/-y only drops gptme's interactive confirmation hooks: "A plugin-registered TOOL_CONFIRM hook is still called" (L236-241). A TOOL_CONFIRM hook that raises skips the call ("On error, skip to be safe", confirm.py), and gptme waits for it with no time limit. Other hooks' exceptions are caught and logged. TOOL_EXECUTE_PRE and TOOL_EXECUTE_POST run before and after every tool; the post hook gets log, workspace, tool_use and the result messages, result_msgs (types.py, tools/base.py). SESSION_START and SESSION_END mark the session. A ToolUse has tool, args, content, kwargs and a call_id that can be None (base.py L919-926). Plugins are packages found in the [plugins] paths of ~/.config/gptme/config.toml or a project's gptme.toml (for example ~/.config/gptme/plugins), narrowed by enabled = [...] when set; gptme calls each hooks/ module's register() at startup (plugins docs L10-60, L143-163). The tools include shell, save, append, patch, read, ipython and browser, plus MCP tools. gptme has 4.5k GitHub stars; v0.36.0 shipped on 2 Nov 2026.
Things to design around:
- Not every tool asks.
TOOL_CONFIRMruns only for tools that call gptme's confirmation:shell,save,append,patchand MCP tools do (execute_with_confirmation), andipythoncallsget_confirmation.readdoesn't ("Built-in read skips execute_with_confirmation() (it is read_only)",read.py), andbrowserdoesn't either. A plugin can't block those calls; list them in the docs as not decided. - A person can still edit an allowed call. Returning
Nonekeeps gptme's own prompt (cli_confirm), where a person can edit the call, so what runs may not be what Tracekit decided. Returningconfirm()skips that prompt. Pick one and say why. WithNone, the post-tool event must record whether the content that ran is the content decided, as the Pydantic AI integration does ("the call's arguments changed after the decision"). - Priority. Register above 200; the docs' own example uses 1000. Hooks sort by priority, then name, both descending.
- gptme and Tracekit live in different Python environments (gptme is usually installed with pipx or
uv tool). So don't importtracekitin the plugin. Like OpenCode's (_opencode_pluginintracekit/agent_hooks.py), make it a small generated plugin that uses only the standard library. It spawnspython -I -m tracekit.integrations.harness_hooks gptme <event>with a Claude-shaped payload, skips the call unless the hook exits 0, and kills a hook still running after 600 s and skips. A plugin whose hook module fails to import is logged, and gptme runs without it (plugins/__init__.py), so doctor checks gptme loads it. - A call may have no id. Give each call an id of the plugin's own, kept with its
ToolUsebetweenTOOL_CONFIRMandTOOL_EXECUTE_POST, ascrewai.pydoes. If gptme runs the post hook for a skipped call, it must not record that call as run.
Task:
- In a real gptme session, with a stub plugin that logs
TOOL_CONFIRM,TOOL_EXECUTE_PRE/POST,SESSION_START/ENDandTURN_PRE, record (redact anything private) theToolUseofshell,save,append,patch,ipython,readand an MCP call, in the markdown tool format and with native tool calls, as cases intests/data/harness/gptme.json. Say here: which tools reachTOOL_CONFIRM; whencall_idis set; whether the post hook runs for a skipped call; what itstool_useholds after a person edits a call in gptme's prompt; how MCP tools are named; whether~/.config/gptme/pluginsis searched with no[plugins] pathsset; whether a project's[plugins] enabledcan leave out a user's plugin; and whetherTURN_PREgives the typed prompt. - Add
gptmetoAGENT_NAMES.tool():shell→Bash(commandfromcontent, or thecommandkwarg),save→Write,appendandpatch→Edit(path: the first arg, or thepathkwarg),read→Read, MCP tools asmcp__<server>__<tool>. Decide howipythonis decided: Tracekit's shell rules don't read Python, and holding it for a person is the safe default (as Coding agents: an extension for Pi (earendil-works/pi) #564 does for Pi'spowershell).normalise()reads the payload the plugin sends, prompts included if step 1 finds them. - Generate
~/.config/gptme/plugins/tracekit/(__init__.py, andhooks/__init__.pywithregister()) with a marker line, refusing to overwrite a plugin Tracekit didn't write, as_install_opencodedoes. If~/.config/gptme/config.tomlhas no[plugins]table, append one with that path, after a backup; if it has one without the path, change nothing and print the line to add (lean:until someone needs a merge). Wiretracekit init --dev [--v2] --agent gptme/uninstall/doctor. - Tests: in
tests/test_agent_hooks.py(the mapping in both formats; the generated plugin'sTOOL_CONFIRMagainst a stub hook command: exit 0 lets the call through, a block, a crash or a kill skips it; the installer's refusal) and the recorded cases throughcases("gptme")intests/test_harness_hooks_v2.py. - Add
~/.config/gptmeandgptme.tomltoTK-F009/TK-F015intracekit/policy2/packs/coding.yaml, a column indocs/coding-agents.md, anddocs/limits.mdrows: tools that never reachTOOL_CONFIRM(read,browser, and any step 1 finds) aren't decided; a plugin gptme can't load lets it run without Tracekit; howipythonis decided.
Done when: in a real gptme session (say which version and tool format in the PR) a denied shell call doesn't run and the model sees the reason, with and without -y; a held call waits for tracekit approvals approve; and the session's calls show up in tracekit last; the tests pass and make test passes.
Comment here to claim it. Commits need a DCO sign-off (git commit -s).
Activity
souravC01 commentedon Nov 4, 2026
Hey @LoopGlitch26, I'd like to take this.
I looked through the issue and checked the OpenCode pattern in
tracekit/agent_hooks.py. Using a small stdlib-only plugin makes total sense here since gptme runs in its own Python env via pipx or uv.I'll start with step 1. I can spin up a local session on gptme v0.36.0 with a stub hook, log the exact
ToolUsepayloads for shell, save, patch, and MCP calls, and record them as test fixtures. After that, I'll wire up theTOOL_CONFIRMhook (setting priority 1000 to out-rank the built-in 200 guardrail), the normalization mappings, and unit tests intests/test_agent_hooks.py.Could you assign #574 to me?
LoopGlitch26 commentedon Nov 4, 2026
It's yours, @souravC01. Step 1 first: record the real
TOOL_CONFIRMandTOOL_EXECUTE_PRE/POSTpayloads from a gptme session, and say the gptme version and tool format in the PR. Commits need a DCO sign-off (git commit -s).LoopGlitch26 commentedon Nov 6, 2026
@souravC01 are you still on this? If you're busy, say so and it opens up for someone else.
souravC01 commentedon Nov 7, 2026
Hey @LoopGlitch26 thanks for checking in. Yes, I’m still working on the gptme integration. If it’s urgent, feel free to take it over or open it up for someone else to pick up. I’m happy to share what I’ve looked into so far.
LoopGlitch26 commentedon Nov 7, 2026
Thanks, good to hear. Ask here if anything about the hook format is unclear.
souravC01 commentedon Nov 12, 2026
I opened #778. I captured the hooks from gptme v0.36.0 with a stub plugin and included the redacted Markdown and native tool calls in
gptme.json.TOOL_CONFIRM. Read and browser bypass confirmation. Markdown didn't setcall_id, and native calls carried the provider's ID. MCP tools came through asserver.tool.ToolUse. That's why the bridge returnsconfirm()on allow.~/.config/gptme/pluginsuntil I configured a plugin path. A project allowlist could exclude the user plugin if neither allowlist named it. I got the typed prompt from the session log atTURN_PRE.I also ran the generated plugin against a real Tracekit v2 dev signer in WSL2. The model got the
TK-D001denial reason with and without-y. The denied command didn't run, the held command ran once aftertracekit approvals approve <id>, andtracekit lastverified all three runs.On Python 3.12, 5,061 tests passed and 476 v2 bundles verified. E17 stopped 100% of deny cases. E21 found 0 regressions across 840 cases. The regenerated policy results matched the committed results under CI's comparison rules.