Git design
How git_spec.md maps onto OKLM. What exists, with evidence, is the "Git" section of gap-analysis.md: the harness has no git code yet, so this is mostly new code on existing foundations.
Status: accepted (the spec's G0); the four decisions below taken on 2026-11-03 as proposed; G1 to G3 done.
Principles
- Git through the
gitcommand, run like any Bash call (permission rules, sandbox, jobs for long operations); no library. - One module,
src/harness/git.c, for what the harness itself needs from git: detection, the snapshot, the classifier, the pre-commit checks, the worktrees. The model's own git work stays Bash calls. - The commands of §11 are prompt commands and skills in the commands framework (commands_spec.md), with their steps written here.
Section by section
| § | Existing | New code |
|---|---|---|
| 1.1 Detection | git.c: rev-parse at start (and after
/cd), default branch, remotes and hosts, operations in
progress, conventions from the last 50 commits, cached per
repository. |
|
| 1.2 Snapshot | agent.c render |
Computed once in oklm_agent_new and appended to the
system text (stable for the KV cache); a reminder when the branch or
HEAD changes, through the event queue of process-design.md. |
| 1.3 Status line | view_status |
Branch, ahead / behind, dirty, operation in progress, in the agent specification's status line. |
| 2 Classifier | permissions.c check_bash, util.c
sh_split |
A git normalizer (drops global options -C,
-c, --git-dir, environment assignments and
redirections) and a classifier: read-only (allowed, plan mode included),
mutating local (asks unless a rule allows), dangerous (asks even when a
rule allows: a pass after the rules turns allow into ask), never
(refused). The table lives in permissions.c next to the rules; settings
can extend it. |
| 2.4 Environment | process.c, jobs.c spawning | GIT_EDITOR=true, GIT_SEQUENCE_EDITOR=true,
GIT_PAGER=cat, PAGER=cat,
GIT_TERMINAL_PROMPT=0 for every command (Linux and
Windows). |
| 2.5 Pre-commit checks | git.c: secret patterns over the staged diff (and
gitleaks when installed), large files, unwanted files; staging limited
to the files the agent edited (the agent specification's checkpoint
registry) or named by the user. |
|
| 3, 4, 6 Commits, branches, conflicts | The steps in the system prompt's git part and in
/commit; protected branches and conventions from settings;
interrupted operations reported at start. |
|
| 5 Hosts | Gitea first: its REST API through src/client/ with the token from
git's credential helper (never printed), or tea when
installed; GitHub through gh. A fake host for tests. |
|
| 7 Archaeology | skills | A git-history skill shipped with OKLM. |
| 8 Review | sub-agents | /diff (the session's edits against the user's),
/code-review with parallel reviewer sub-agents (needs the
agent specification's parallel foreground calls and agent types),
/security-review, /simplify. |
| 9 Worktrees | git.c: create under
.oklm/worktrees/<name> on
oklm/<name>, the worktree's git common directory
added to the sandbox's writable set, isolation: "worktree"
on the Agent tool, cleanup without force. |
|
| 12 Settings | git.* keys in the agent specification's settings
module. |
|
| 13 CI | .gitea/workflows/ci.yml |
A Gitea Actions template running oklm agent -p on a
self-hosted runner. |
Decisions
Taken on 2026-11-03, each as proposed (the network one waits for the per-job network permission, needed by push and fetch in G4 and G7):
- Network in the sandbox. Fetch, push and host access
fail in a sandboxed session without
--allow-network. Proposed: the per-job network permission of process-design.md (a question unless a rule allowsgit push/git fetchto reach the network). - Plan mode. Proposed: classified read-only git commands run in plan mode (today every Bash call is denied there).
- Trailer setting name. The spec says
git.coAuthorandgit.coAuthorTrailer; proposed:git.coAuthorTrailer. - Gitea access. Proposed: the REST API with the
credential helper's token,
teawhen present.
Order
G1 to G3 after the agent specification's M4 to M6 (permissions, settings, prompt); G5 needs its sessions; G7 the host decision; G8 and G9 its sub-agent work (M12).