feat(sdk): contrat permissions.workspaceExec pour l'exécution contrôlée via l'hôte — #346

Cadrage capacités plugin SCM (#346): le manifeste plugin gagne
permissions.workspaceExec.allow — règles d'exécution contrôlée par l'hôte
(commande bare ASCII résolue sans shell, argv exact avec jeton `*` en
suffixe, cwd project-relative sûr, effect read/write/network/destructive,
64 règles max) — au lieu de lectures ad hoc du store interne .git.
Validation manifeste + exports runtime/index + docs README/manifest/
services + auto-check script étendu (règles valides acceptées, règles
unsafe rejetées).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/manifest.md

@@ -141,6 +141,39 @@ development loop.
 - `activationScope`: `"app"` by default, or `"project"` when activation needs a
   focused project immediately.
 - `capabilities`: `"ui"`, `"tooling"` and/or `"mcp"`.
+- `permissions.workspaceExec`: explicit generic executable rules used by
+  `ctx.services.workspace.execTool()`.
+
+## Workspace execution permissions
+
+Short project-scoped executable access is denied unless the active plugin
+manifest contains a matching rule:
+
+```json
+{
+  "permissions": {
+    "workspaceExec": {
+      "allow": [
+        {
+          "command": "tool",
+          "args": ["status", "*"],
+          "cwd": ".",
+          "effect": "read"
+        }
+      ]
+    }
+  }
+}
+```
+
+`command` is a bare ASCII executable name; paths and shell command lines are
+rejected. `args` is an argv pattern: literal tokens match exactly, `*` matches
+one token, and a final `*` matches the remaining suffix (including no token).
+`cwd` is an exact normalized project-relative directory; `*` permits any cwd
+that the host still proves is under the project root. `effect` is one of
+`read`, `write`, `network`, or `destructive` and drives sandbox/audit policy.
+The manifest declares generic process access only; it does not add native SCM
+semantics to IdeA.
 
 ## Contributions
 

docs/services.md

@@ -29,6 +29,38 @@ Key APIs:
 - `stat(path, projectId?)`
 - `watch(path, handler, projectId?)`
 - `queryStructure(query?)`
+- `execTool(request)`
+
+### Short external tools
+
+`services.workspace.execTool()` runs a short external executable already available
+to the host. It is generic: IdeA does not expose Git, SVN, formatter, or linter
+semantics. The plugin owns the arguments and parses the returned output.
+
+```ts
+const result = await ctx.services!.workspace.execTool({
+  projectId,
+  command: "tool",
+  args: ["status", "--short"],
+  cwd: ".",
+  timeoutMs: 5_000,
+  maxStdoutBytes: 256_000,
+  maxStderrBytes: 64_000
+});
+```
+
+The host passes `command` and `args` directly without a shell. The plugin must
+declare a matching `permissions.workspaceExec.allow` rule, be active for the
+project, and use a project-relative `cwd`. IdeA canonicalizes the cwd, bounds
+time/stdin/output/concurrency, exposes only an allowlisted environment, applies
+the project filesystem sandbox where supported, and audits metadata without
+captured stdout/stderr contents. This API returns output directly and never
+creates a visible Work/background-task entry.
+
+Current host maxima are 30 seconds, 1,000,000 stdout bytes, 256,000 stderr bytes,
+and 64,000 stdin bytes. Requested output/time values above a maximum are clamped;
+zero is rejected. Output is returned as lossy UTF-8 with explicit truncation
+flags.
 
 ## Tasks