Skip to content

Commit 246dfa6

Browse files
authored
Merge pull request #161 from aictrl-dev/feat/issue-156-bash-git-optin
feat(tool): drop git commit/PR prose from the bash tool description (#156)
2 parents 3e075b5 + 6584c7b commit 246dfa6

5 files changed

Lines changed: 158 additions & 72 deletions

File tree

‎README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,15 @@ In headless mode, Aictrl automatically rejects all interactive permission reques
7474

7575
Set `AICTRL_HEADLESS=true` in your environment to force headless behavior even in pseudo-TTYs.
7676

77+
### Restricting Dangerous Commands
78+
79+
Tool descriptions describe tools; they are not a security boundary. Block
80+
dangerous commands with `permission.bash` rules, for example denying force
81+
pushes, hook skipping, git config changes and `git -c` overrides (`"git -c *": "deny"`,
82+
which also blocks harmless `-c` uses). The CLI ships no such rules by default. See the
83+
[configuration reference](packages/cli/README.md#restricting-dangerous-commands)
84+
for an example.
85+
7786
### Model Stream Idle Timeout
7887

7988
Model stream idle timeouts are disabled by default. Set

‎packages/cli/README.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,46 @@ Use `--variant` to select provider-specific reasoning effort. For OpenAI-compati
137137
Ollama models, `--variant none` sends `reasoning_effort: "none"` to disable
138138
thinking; model `options` can also set `reasoning_effort: "none"` directly.
139139

140+
### Restricting Dangerous Commands
141+
142+
Prompt text is not a security boundary, so the `bash` tool description does not
143+
carry git policy or a commit/PR procedure. Block dangerous commands with
144+
`permission.bash` rules in `aictrl.json` (or inline via `AICTRL_CONFIG_CONTENT`):
145+
146+
```json
147+
{
148+
"permission": {
149+
"bash": {
150+
"git push *--force*": "deny",
151+
"git push -f*": "deny",
152+
"git push * -f*": "deny",
153+
"git * --no-verify*": "deny",
154+
"git config *": "deny",
155+
"git -c *": "deny"
156+
}
157+
}
158+
}
159+
```
160+
161+
- `git push *--force*` also denies `--force-with-lease`, on purpose.
162+
- `git -c *` closes overrides such as `git -c core.hooksPath=/dev/null commit`,
163+
which would otherwise skip hooks without `--no-verify`. It also blocks harmless
164+
`-c` uses.
165+
166+
Each command in a bash call (including each part of `a && b`) is matched against
167+
the patterns. `*` matches any text, and a trailing ` *` also matches the bare
168+
command (`git config *` matches `git config`). When several rules match, the last
169+
one in the config wins. Commands that match no rule keep the agent's default
170+
(`allow` for `bash` in the default `build` agent).
171+
172+
Patterns match the command text. They fail closed on false positives, so
173+
`git commit -m "remove --no-verify"` is denied too. They also cannot catch every
174+
spelling, for example a script that runs git.
175+
176+
If your agents should commit or open PRs, supply your own procedure through a
177+
skill, `AGENTS.md` or the `instructions` config, and run the CLI in an isolated
178+
environment with credentials scoped to what the task needs.
179+
140180
## Local Development
141181

142182
```bash

‎packages/cli/src/tool/bash.ts‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -94,9 +94,10 @@ export const BashTool = Tool.define("bash", async () => {
9494
log.info("bash tool using shell", { shell })
9595

9696
return {
97-
description: DESCRIPTION.replaceAll("${directory}", Instance.directory)
98-
.replaceAll("${maxLines}", String(Truncate.MAX_LINES))
99-
.replaceAll("${maxBytes}", String(Truncate.MAX_BYTES)),
97+
// Replacer functions insert values literally, without `$` pattern expansion
98+
description: DESCRIPTION.replaceAll("${directory}", () => Instance.directory)
99+
.replaceAll("${maxLines}", () => String(Truncate.MAX_LINES))
100+
.replaceAll("${maxBytes}", () => String(Truncate.MAX_BYTES)),
100101
parameters: z.object({
101102
command: z.string().describe("The command to execute"),
102103
timeout: z.number().describe("Optional timeout in milliseconds").optional(),

‎packages/cli/src/tool/bash.txt‎

Lines changed: 0 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -45,71 +45,3 @@ Usage notes:
4545
<bad-example>
4646
cd /foo/bar && pytest tests
4747
</bad-example>
48-
49-
# Committing changes with git
50-
51-
Only create commits when requested by the user. If unclear, ask first. When the user asks you to create a new git commit, follow these steps carefully:
52-
53-
Git Safety Protocol:
54-
- NEVER update the git config
55-
- NEVER run destructive/irreversible git commands (like push --force, hard reset, etc) unless the user explicitly requests them
56-
- NEVER skip hooks (--no-verify, --no-gpg-sign, etc) unless the user explicitly requests it
57-
- NEVER run force push to main/master, warn the user if they request it
58-
- Avoid git commit --amend. ONLY use --amend when ALL conditions are met:
59-
(1) User explicitly requested amend, OR commit SUCCEEDED but pre-commit hook auto-modified files that need including
60-
(2) HEAD commit was created by you in this conversation (verify: git log -1 --format='%an %ae')
61-
(3) Commit has NOT been pushed to remote (verify: git status shows "Your branch is ahead")
62-
- CRITICAL: If commit FAILED or was REJECTED by hook, NEVER amend - fix the issue and create a NEW commit
63-
- CRITICAL: If you already pushed to remote, NEVER amend unless user explicitly requests it (requires force push)
64-
- NEVER commit changes unless the user explicitly asks you to. It is VERY IMPORTANT to only commit when explicitly asked, otherwise the user will feel that you are being too proactive.
65-
66-
1. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following bash commands in parallel, each using the Bash tool:
67-
- Run a git status command to see all untracked files.
68-
- Run a git diff command to see both staged and unstaged changes that will be committed.
69-
- Run a git log command to see recent commit messages, so that you can follow this repository's commit message style.
70-
2. Analyze all staged changes (both previously staged and newly added) and draft a commit message:
71-
- Summarize the nature of the changes (eg. new feature, enhancement to an existing feature, bug fix, refactoring, test, docs, etc.). Ensure the message accurately reflects the changes and their purpose (i.e. "add" means a wholly new feature, "update" means an enhancement to an existing feature, "fix" means a bug fix, etc.).
72-
- Do not commit files that likely contain secrets (.env, credentials.json, etc.). Warn the user if they specifically request to commit those files
73-
- Draft a concise (1-2 sentences) commit message that focuses on the "why" rather than the "what"
74-
- Ensure it accurately reflects the changes and their purpose
75-
3. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following commands:
76-
- Add relevant untracked files to the staging area.
77-
- Create the commit with a message
78-
- Run git status after the commit completes to verify success.
79-
Note: git status depends on the commit completing, so run it sequentially after the commit.
80-
4. If the commit fails due to pre-commit hook, fix the issue and create a NEW commit (see amend rules above)
81-
82-
Important notes:
83-
- NEVER run additional commands to read or explore code, besides git bash commands
84-
- NEVER use the TodoWrite or Task tools
85-
- DO NOT push to the remote repository unless the user explicitly asks you to do so
86-
- IMPORTANT: Never use git commands with the -i flag (like git rebase -i or git add -i) since they require interactive input which is not supported.
87-
- If there are no changes to commit (i.e., no untracked files and no modifications), do not create an empty commit
88-
89-
# Creating pull requests
90-
Use the gh command via the Bash tool for ALL GitHub-related tasks including working with issues, pull requests, checks, and releases. If given a GitHub URL use the gh command to get the information needed.
91-
92-
IMPORTANT: When the user asks you to create a pull request, follow these steps carefully:
93-
94-
1. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following bash commands in parallel using the Bash tool, in order to understand the current state of the branch since it diverged from the main branch:
95-
- Run a git status command to see all untracked files
96-
- Run a git diff command to see both staged and unstaged changes that will be committed
97-
- Check if the current branch tracks a remote branch and is up to date with the remote, so you know if you need to push to the remote
98-
- Run a git log command and `git diff [base-branch]...HEAD` to understand the full commit history for the current branch (from the time it diverged from the base branch)
99-
2. Analyze all changes that will be included in the pull request, making sure to look at all relevant commits (NOT just the latest commit, but ALL commits that will be included in the pull request!!!), and draft a pull request summary
100-
3. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following commands in parallel:
101-
- Create new branch if needed
102-
- Push to remote with -u flag if needed
103-
- Create PR using gh pr create with the format below. Use a HEREDOC to pass the body to ensure correct formatting.
104-
<example>
105-
gh pr create --title "the pr title" --body "$(cat <<'EOF'
106-
## Summary
107-
<1-3 bullet points>
108-
</example>
109-
110-
Important:
111-
- DO NOT use the TodoWrite or Task tools
112-
- Return the PR URL when you're done, so the user can see it
113-
114-
# Other common operations
115-
- View comments on a GitHub PR: gh api repos/foo/bar/pulls/123/comments

‎packages/cli/test/tool/bash.test.ts‎

Lines changed: 105 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,10 @@ import { BashTool, MAX_OUTPUT_BUFFER } from "../../src/tool/bash"
55
import { Instance } from "../../src/project/instance"
66
import { Filesystem } from "../../src/util/filesystem"
77
import { tmpdir } from "../fixture/fixture"
8-
import type { PermissionNext } from "../../src/permission/next"
8+
import { PermissionNext } from "../../src/permission/next"
9+
import { Agent } from "../../src/agent/agent"
10+
import { Session } from "../../src/session"
11+
import type { Config } from "../../src/config/config"
912
import { Truncate } from "../../src/tool/truncation"
1013

1114
const ctx = {
@@ -41,6 +44,107 @@ describe("tool.bash", () => {
4144
})
4245
})
4346

47+
describe("tool.bash description", () => {
48+
async function description(directory: string) {
49+
return Instance.provide({
50+
directory,
51+
fn: async () => (await BashTool.init()).description,
52+
})
53+
}
54+
55+
test("describes only the tool, with no git procedure or git policy", async () => {
56+
await using tmp = await tmpdir()
57+
const text = await description(tmp.path)
58+
expect(text).not.toContain("# Committing changes with git")
59+
expect(text).not.toContain("# Creating pull requests")
60+
expect(text).not.toContain("# Git safety")
61+
expect(text).not.toContain("--no-verify")
62+
expect(text).not.toContain("git config")
63+
expect(text).not.toContain("gh pr create")
64+
expect(text).not.toContain("${")
65+
})
66+
67+
test("inserts the working directory literally", async () => {
68+
await using tmp = await tmpdir({
69+
init: async (dir) => {
70+
const nested = path.join(dir, "a$&b")
71+
await Bun.write(path.join(nested, ".keep"), "")
72+
return nested
73+
},
74+
})
75+
const text = await description(tmp.extra)
76+
expect(text).toContain(`All commands run in ${tmp.extra} by default`)
77+
})
78+
})
79+
80+
describe("tool.bash dangerous git commands", () => {
81+
// Keep in sync with the "Restricting dangerous commands" example in packages/cli/README.md.
82+
const permission = {
83+
bash: {
84+
"git push *--force*": "deny",
85+
"git push -f*": "deny",
86+
"git push * -f*": "deny",
87+
"git * --no-verify*": "deny",
88+
"git config *": "deny",
89+
"git -c *": "deny",
90+
},
91+
} satisfies Config.Info["permission"]
92+
93+
type Guarded = {
94+
run: (command: string) => Promise<unknown>
95+
ruleset: PermissionNext.Ruleset
96+
}
97+
98+
// Wires `ask` the way session/prompt.ts does: the agent's rules merged with the session's.
99+
async function withBuildAgent(fn: (guarded: Guarded) => Promise<void>) {
100+
await using tmp = await tmpdir({ git: true, config: { permission } })
101+
await Instance.provide({
102+
directory: tmp.path,
103+
fn: async () => {
104+
const agent = await Agent.get("build")
105+
const session = await Session.create({ title: "Dangerous git commands" })
106+
const ruleset = PermissionNext.merge(agent.permission, session.permission ?? [])
107+
const bash = await BashTool.init()
108+
const guarded = {
109+
...ctx,
110+
sessionID: session.id,
111+
ask: (req: Omit<PermissionNext.Request, "id" | "sessionID" | "tool">) =>
112+
PermissionNext.ask({ ...req, sessionID: session.id, ruleset }),
113+
}
114+
await fn({ run: (command) => bash.execute({ command, description: "Run git" }, guarded), ruleset })
115+
},
116+
})
117+
}
118+
119+
test.each([
120+
"git push --force origin main",
121+
"git push --force-with-lease",
122+
"git push -f",
123+
"git push origin main -f",
124+
"git commit --no-verify -m wip",
125+
"git commit -m wip --no-verify",
126+
"git push --no-verify",
127+
"git config user.name someone",
128+
"git config --global core.hooksPath /dev/null",
129+
"git -c core.hooksPath=/dev/null commit -m wip",
130+
"git status && git push --force",
131+
])("denies %s", async (command) => {
132+
await withBuildAgent(async (guarded) => {
133+
await expect(guarded.run(command)).rejects.toBeInstanceOf(PermissionNext.DeniedError)
134+
})
135+
})
136+
137+
test("allows other git commands", async () => {
138+
await withBuildAgent(async (guarded) => {
139+
const result = (await guarded.run("git status")) as { metadata: { exit: number } }
140+
expect(result.metadata.exit).toBe(0)
141+
for (const command of ["git push origin feature-fix", "git commit -m wip", "git log --oneline"]) {
142+
expect(PermissionNext.evaluate("bash", command, guarded.ruleset).action).toBe("allow")
143+
}
144+
})
145+
})
146+
})
147+
44148
describe("tool.bash permissions", () => {
45149
test("asks for bash permission with correct pattern", async () => {
46150
await using tmp = await tmpdir({ git: true })

0 commit comments

Comments
 (0)